Next: , Up: Running LilyPond



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

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 access to some internal variables. Use -e '(ly:option-usage)' for more information.
-f,--format=format
which formats should be written. Choices are svg, ps, pdf, png, tex, dvi.
-b,--backend=format
the output format to use for the back-end. Choices 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.
ps
for PostScript
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)
scm
for a dump of the raw, internal Scheme-based drawing commands.


-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. 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., -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 be limited in both 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:

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 them 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/2.4.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.


Footnotes

[1] The status of GUILE is not reset after processing a .ly file, so be careful not to change any system defaults from within Scheme.


Read comments on this page, or add one.

This page is for LilyPond-2.5.11 (development-branch).

Report errors to <bug-lilypond@gnu.org>.

Other languages: English.
Using automatic language selection.