LilyPond Application Usage: 1.2 Command-line usage

[ << Running lilypond ]	[Top][Contents][Index][ ? ]			[ Updating files with convert-ly >> ]
[ < Normal usage ]		[ Up : Running lilypond ]	[ Invoking LilyPond > ]

1.2 Command-line usage

This section contains extra information about using LilyPond on the command-line. This may be desirable to pass extra options to the program. In addition, there are certain extra ‘helper’ programs (such as midi2ly) which are only available on the command-line.

By ‘command-line’, we mean the command line in the operating system. Windows users might be more familiar with the terms ‘DOS shell’ or ‘command shell’. MacOS X users might be more familiar with the terms ‘terminal’ or ‘console’. Some additional setup is required for MacOS X users; please see MacOS X.

Describing how to use this part of an operating system is outside the scope of this manual; please consult other documentation on this topic if you are unfamiliar with the command-line.

[ << Running lilypond ]	[Top][Contents][Index][ ? ]			[ Updating files with convert-ly >> ]
[ < Command-line usage ]		[ Up : Command-line usage ]	[ > ]

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.ps’ and ‘filename.pdf’ as output. Several files can be specified; they will each be processed independently. ¹

If ‘filename.ly’ contains more than one \book block, then the rest of the scores will be output in numbered files, starting with ‘filename-1.pdf’. In addition, the value of output-suffix will be inserted between the basename and the number. An input file containing

#(define output-suffix "violin")
\score { … }
#(define output-suffix "cello")
\score { … }

will output base‘-violin.pdf’ and base‘-cello-1.pdf’.

[ << Running lilypond ]	[Top][Contents][Index][ ? ]			[ Updating files with convert-ly >> ]
[ < Invoking LilyPond ]		[ Up : Invoking LilyPond ]	[ Basic command line options for LilyPond > ]

Using LilyPond with standard shell features

Since LilyPond is a command line application, features of the ‘shell’ used for calling LilyPond can also be put to good use.

For example:

lilypond *.ly

will process all LilyPond files in the current directory.

Redirecting the console output (e.g. to a file) may also be useful:

lilypond file.ly 1> stdout.txt

lilypond file.ly 2> stderr.txt

lilypond file.ly &> all.txt

Redirects ‘normal’ output, ‘errors’ only or ‘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.

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.

find . -name '*.ly' -exec lilypond '{}' \;

This should also work for MacOS X users.

A Windows user would run;

forfiles /s /M *.ly /c "cmd /c lilypond @file"

entering these commands in a command prompt usually found under Start > Accessories > Command Prompt or for version 8 users, by typing in the search window ‘command prompt’.

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 /p option;

forfiles /s /p C:\Documents\MyScores /M *.ly /c "cmd /c lilypond @file"

If there are spaces in the path to the top-level folder, then the whole path needs to be inside double quotes;

forfiles /s /p "C:\Documents\My Scores" /M *.ly /c "cmd /c lilypond @file"

[ << Running lilypond ]	[Top][Contents][Index][ ? ]			[ Updating files with convert-ly >> ]
[ < ]		[ Up : Command-line usage ]	[ Advanced command line options for LilyPond > ]

Basic command line options for LilyPond

The following options are supported:

-b, --bigpdfs

PDF files generated will be much larger than normal (due to little or no font optimization). However, if two or more PDF files are included within pdftex, xetex or luatex documents they can then be processed further via ghostscript (merging duplicated font data) resulting in significantly smaller PDF files.

lilypond -b myfile

Then run ghostscript;

gs -q -sDEVICE=pdfwrite -dPDFDontUseFontObjectNum -o gsout.pdf myfile.pdf

Note: For Ghostscript versions 9.17 and above, the -dPDFDontUseFontObjectNum option is required to remove any duplicate font data.

pdfsizeopt.py can then be used to further optimize the size of file;

pdfsizeopt.py --use-multivalent=no gsout.pdf final.pdf

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

See Advanced command line options for LilyPond.

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

Note: Windows users must use double quotes instead of single quotes.

-f, --format=format

which formats should be written. Choices for format are ps, pdf, and png.

Example: lilypond -fpng filename.ly

For svg and eps formats use the -dbackend option. See Advanced command line options for LilyPond.

-h, --help

Show a summary of usage.

-H, --header=FIELD

Dump a header field to file ‘BASENAME.FIELD’.

-i, --init=file

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

-I, --include=directory

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

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

Run lilypond in a chroot jail.

The ‘--jail’ option provides a more flexible alternative to ‘-dsafe’, when LilyPond formatting is being provided via a web server, or whenever LilyPond executes commands sent by external sources (see Advanced command line options for LilyPond).

It 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 can be a relatively complex matter, as we must be sure that LilyPond is able to find whatever it needs to compile the source inside the jail itself. A typical chroot jail will comprise the following steps:

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 have already mentioned, it must be run with superuser privileges (which, of course, it will lose immediately), possibly using sudo. It is also good practice 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. Also see LilyPond in chroot jail.

-l, --loglevel=LEVEL

Set the verbosity of the console output to LEVEL. Possible values are:

NONE: No output at all, not even error messages.
ERROR: Only error messages, no warnings or progress messages.
WARN: Warnings and error messages, no progress.
BASIC_PROGRESS: Basic progress messages (success), warnings and errors.
PROGRESS: All progress messages, warnings and errors.
INFO (default): Progress messages, warnings, errors and further execution information.
DEBUG: All possible messages, including verbose debug output.

-o, --output=FILE or FOLDER

Set the default output file to FILE or, if a folder with that name exists, direct the output to FOLDER, taking the file name from the input file. The appropriate suffix will be added (e.g. .pdf for pdf) in both cases.

--ps

Generate PostScript.

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

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

[ << Running lilypond ]	[Top][Contents][Index][ ? ]			[ Updating files with convert-ly >> ]
[ < Basic command line options for LilyPond ]		[ Up : Command-line usage ]	[ Environment variables > ]

Advanced command line options for LilyPond

-d[option-name]=[value],

–define-default=[option-name]=[value] This sets the equivalent internal Scheme function to value. For example;

-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. For example;

-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 a higher resolution (using the given factor) and scale down the result to prevent ‘jaggies’ in `PNG` images.
`aux-files`	`#t`	Create `.tex`, `.texi` and `.count` files when used with the `eps` backend option.
`backend`	`ps`	This is the default setting. Postscript files (default) include `TTF`, `Type1` and `OTF` fonts. No ‘subsetting’ of these fonts is done. Be aware that using ‘oriental’ character sets can lead to very large file sizes.
	`eps`	Used as default by the `lilypond-book` command. This dumps every page as both a single file with all pages and fonts included and as separate encapsulated postscript files for each page but without fonts included.
	`null`	Do not output a printed score. This has the same effect as `-dno-print-pages`.
	`scm`	This dumps out the raw, internal Scheme-based drawing commands.
	`svg`	Scalable Vector Graphics. A single SVG file is created for every page of output. Music glyphs are encoded as vector graphics, but text fonts are not embedded in the SVG files. Any SVG viewer will therefore need the relevant text fonts to be available to it for proper rendering of both text and lyrics. It is recommended to not use font ‘lists’ or ‘aliases’ in case an SVG viewer is unable to handle them. When using Web Open Font Format (WOFF) files the additional `--svg-woff` switch is required.
`check-internal-types`	`#f`	Check every property assignment for types.
`clip-systems`	`#f`	Extract music fragments out of a score. This requires that the `clip-regions` function has been defined within the `\layout` block. See Extracting fragments of music. No fragments are extracted though if used with the ‘`-dno-print-pages`’ option.
`crop`	`#f`	Match the size of the normal output to the typeset image.
`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.
`embed-source-code`	`#f`	Embed the LilyPond source files inside the generated PDF document.
`eps-box-padding`	`#f`	Pad left edge of the output EPS bounding box by the given amount (in mm).
`font-export-dir`	`#f [dir]`	Directory for exporting fonts as PostScript files.
`gs-load-fonts`	`#f`	Load fonts via Ghostscript.
`gs-load-lily-fonts`	`#f`	Load only the LilyPond fonts via Ghostscript.
`gs-never-embed-fonts`	`#f`	Make Ghostscript embed only TrueType fonts and no other font format.
`gui`	`#f`	Runs silently and redirect all output to a log file.

Note 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 [file]`	If string `FOO` is given as a 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`	`#t`	Add ‘point & click’ links to PDF and SVG 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`’ or ‘`-dcrop`’.
`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 [file]`	Specify name of a file which 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,

#(s ystem "rm -rf /")  % too dangerous to write correctly
{
  c4^$(ly:gulp-file "/etc/passwd") % malicious but not destructive
}

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 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.
`svg-woff`	`#f`	This option is required when using Web Open Font Format (WOFF) font files with the backend `svg` command. A single SVG file is created for every page of output. Apart from LilyPond’s own music glyphs, no other font information will be included. Any SVG viewer will therefore require the fonts be available to it for the proper rendering of both text and lyrics. It is also recommended not to use any font ‘aliases’ or ‘lists’ in case the SVG viewer cannot handle them.
`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.

[ << Running lilypond ]	[Top][Contents][Index][ ? ]			[ Updating files with convert-ly >> ]
[ < Advanced command line options for LilyPond ]		[ Up : Command-line usage ]	[ LilyPond in chroot jail > ]

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_LOGLEVEL: The default loglevel. If LilyPond is called without an explicit loglevel (i.e. no ‘--loglevel’ command line option), this value is used.
LILYPOND_GC_YIELD: A variable, as a percentage, that tunes memory management behavior. A higher values means the program uses more memory, a smaller value means more CPU time is used. The default value is 70.

[ << Running lilypond ]	[Top][Contents][Index][ ? ]			[ Updating files with convert-ly >> ]
[ < Environment variables ]		[ Up : Command-line usage ]	[ Error messages > ]

LilyPond in chroot jail

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 GNU/Linux, and may require the use of sudo as appropriate.

Install the necessary packages: LilyPond, GhostScript, and ImageMagick.
Create a new user by the name of lily:
```
adduser lily
```
This will create a new group for the lily user as well, and a home folder, /home/lily
In the home folder of the lily user create a file to use as a separate filesystem:
```
dd if=/dev/zero of=/home/lily/loopfile bs=1k count= 200000
```
This example creates a 200MB file for use as the jail filesystem.

Create a loop device, make a file system and mount it, then create a folder that can be written by the lily user:

mkdir /mnt/lilyloop
losetup /dev/loop0 /home/lily/loopfile
mkfs -t ext3 /dev/loop0 200000
mount -t ext3 /dev/loop0 /mnt/lilyloop
mkdir /mnt/lilyloop/lilyhome
chown lily /mnt/lilyloop/lilyhome

In the configuration of the servers, the JAIL will be /mnt/lilyloop and the DIR will be /lilyhome.

Create a big directory tree in the jail by copying the necessary files, as shown in the sample script below.

You can use sed to create the necessary copy commands for a given executable:

for i in "/usr/local/lilypond/usr/bin/lilypond" "/bin/sh" "/usr/bin/;  \
  do ldd $i | sed 's/.*=> \/\(.*\/\)\([^(]*\).*/mkdir -p \1 \&\&  \
    cp -L \/\1\2 \1\2/' | sed 's/\t\/\(.*\/\)\(.*\) (.*)$/mkdir -p  \
      \1 \&\& cp -L \/\1\2 \1\2/' | sed '/.*=>.*/d'; done

Example script for 32-bit Ubuntu 8.04

#!/bin/sh
## defaults set here

username=lily
home=/home
loopdevice=/dev/loop0
jaildir=/mnt/lilyloop
# the prefix (without the leading slash!)
lilyprefix=usr/local
# the directory where lilypond is installed on the system
lilydir=/$lilyprefix/lilypond/

userhome=$home/$username
loopfile=$userhome/loopfile
adduser $username
dd if=/dev/zero of=$loopfile bs=1k count=200000
mkdir $jaildir
losetup $loopdevice $loopfile
mkfs -t ext3 $loopdevice 200000
mount -t ext3 $loopdevice $jaildir
mkdir $jaildir/lilyhome
chown $username $jaildir/lilyhome
cd $jaildir

mkdir -p bin usr/bin usr/share usr/lib usr/share/fonts $lilyprefix tmp
chmod a+w tmp

cp -r -L $lilydir $lilyprefix
cp -L /bin/sh /bin/rm bin
cp -L /usr/bin/convert /usr/bin/gs usr/bin
cp -L /usr/share/fonts/truetype usr/share/fonts

# Now the library copying magic
for i in "$lilydir/usr/bin/lilypond" "$lilydir/usr/bin/guile" "/bin/sh"  \
  "/bin/rm" "/usr/bin/gs" "/usr/bin/convert"; do ldd $i | sed 's/.*=>  \
    \/\(.*\/\)\([^(]*\).*/mkdir -p \1 \&\& cp -L \/\1\2 \1\2/' | sed  \
      's/\t\/\(.*\/\)\(.*\) (.*)$/mkdir -p \1 \&\& cp -L \/\1\2 \1\2/'  \
        | sed '/.*=>.*/d'; done | sh -s

# The shared files for ghostscript...
      cp -L -r /usr/share/ghostscript usr/share
# The shared files for ImageMagick
      cp -L -r /usr/lib/ImageMagick* usr/lib

### Now, assuming that you have test.ly in /mnt/lilyloop/lilyhome,
### you should be able to run:
### Note that /$lilyprefix/bin/lilypond is a script, which sets the
### LD_LIBRARY_PATH - this is crucial
      /$lilyprefix/bin/lilypond -jlily,lily,/mnt/lilyloop,/lilyhome test.ly

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.

[ << Running lilypond ]	[Top][Contents][Index][ ? ]			[ Updating files with convert-ly >> ]
[ < Environment variables ]		[ Up : Command-line usage ]	[ Error messages > ]

Other languages: català, deutsch, español, français, magyar, italiano, 日本語.
About automatic language selection.

Invoking `lilypond`
Basic command line options for LilyPond
Advanced command line options for LilyPond
Environment variables
LilyPond in chroot jail