[ << 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.
Invoking lilypond | ||
Command line options for lilypond | ||
Environment variables | ||
LilyPond in chroot jail |
[ << 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. 1
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 ] | [ Command line options for lilypond > ] |
Standard shell commands
If your shell (i.e. command window) supports normal redirects, then you might find it useful to use the following commands to redirect console output to a file:
-
lilypond file.ly 1>stdout.log
to redirect normal output -
lilypond file.ly 2>stderr.log
to redirect error messages -
lilypond file.ly &>all.log
to redirect all output
Consult the documentation for your shell to see if it supports these options, or if the syntax is different. Note that these are shell commands and have nothing to do with lilypond.
[ << Running lilypond ] | [Top][Contents][Index][ ? ] | [ Updating files with convert-ly >> ] | ||
[ < ] | [ Up : Command-line usage ] | [ Environment variables > ] |
Command line options for lilypond
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, uselilypond -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
areps
,pdf
, andpng
.Example:
lilypond -fpng 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'
Here are a few interesting options.
- ‘help’
Running
lilypond -dhelp
will print all of the-d
options available.- ‘paper-size’
This option sets the default paper-size,
-dpaper-size=\"letter\"
Note that the string must be enclosed in escaped quotes (
\"
).- ‘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
-dsafe
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 mode 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.
-dsafe
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.The safe mode will prevent many useful LilyPond snippets from being compiled. The
--jail
is a more secure alternative, but requires more work to set up.- ‘backend’
the output format to use for the back-end. Choices for
format
are-
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 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/lilypond/VERSION/fonts/otf/’) to ‘~/.fonts/’. The SVG output should be compatible with any SVG editor or user agent.
-
scm
-
for a dump of the raw, internal Scheme-based drawing commands.
-
null
do not output a printed score; has the same effect as
-dno-print-pages
.
Example:
lilypond -dbackend=svg filename.ly
-
- ‘preview’
-
Generate an output file containing the titles and the first system of music. If
\bookpart
blocks are used, the titles and first system of every\bookpart
will appear in the output. Theps
,eps
, andsvg
backends support this option. - ‘print-pages’
Generate the full pages, the default.
-dno-print-pages
is useful in combination with-dpreview
.
-
-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.
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.
-
-i,--init=file
Set init file to file (default: ‘init.ly’).
-
-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
.-
-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 oflilypond
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 worklilypond
must be run as root, which is usually accomplished in a safe way usingsudo
.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
, andnosuid
. 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 usingsudo
. It is a good idea to limit the number of seconds of CPU time LilyPond can use (e.g., usingulimit -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!)
[ << Running lilypond ] | [Top][Contents][Index][ ? ] | [ Updating files with convert-ly >> ] | ||
[ < 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_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
.
[ << 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 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 > ] |