lilypond-usage: Basic command line options for LilyPond
Basic command line options for LilyPond
---------------------------------------
The following options are supported:
‘-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’
‘-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*!)
Info Catalog
lilypond-usage: Invoking lilypond
lilypond-usage: Command-line usage
lilypond-usage: Advanced command line options for LilyPond