[ << Running lilypond ] | [Top][Contents][Index] | [ Updating files with convert-ly >> ] |
[ < Invoking lilypond ] | [ Up : Command-line usage ] | [ Advanced 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 are evaluated sequentially.
The expression is evaluated in the
guile-user
module, so if you want to use a definition like(define-public a 42)
as expr, uselilypond -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.
-
-E
,--eps
Generate EPS files.
This option is equivalent to specifying
-dseparate-page-formats=eps -dtall-page-formats=eps
.-
-f
,--format=
format The format of the (main) output file or files. Possible values for format are
ps
,pdf
,png
orsvg
.Example:
lilypond -fpng foo.ly
SVG internally uses a specific backend, and therefore cannot be obtained in the same run as other formats; using
-fsvg
or--svg
is actually equivalent to using the-dbackend=svg
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’.
As an example, let’s assume that you have an input file ‘foo.ly’ containing
\header { title = "bar" } \score { c1 }
The command
lilypond -H title foo.ly
then creates a plain text file ‘foo.title’ containing the string
bar
.-
-i
,--init=
file Set init file to file (default: ‘init.ly’).
-
-I
,--include=
directory Append directory to the search path for input files with relative paths. By default, only the current working directory gets searched.
Multiple ‘-I’ options may be given. The search starts in the current working directory, and if the file to be included is not found the search continues in the directory given by the first ‘-I’ option, then the directory in the second ‘-I’ option, and so on.
Note: Using the tilde character (
~
) with the ‘-I’ switch may produce unexpected results in some shells.Windows users need to include a trailing slash for the directory’s path.
-
-j
,--jail=
user,
group,
jail,
dir [This option is only available if your operating system supports the
chroot
functionality. In particular, Windows doesn’t support it.]Run
lilypond
in a chroot jail.The ‘--jail’ option can be used for security 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). Because LilyPond provides the ability to run Guile programs, it is essential in such scenarios to run it in a sandboxed way so that the file being compiled does not wreak havoc on the system, for example with
% too dangerous to write correctly #(s ystem "rm -rf /") % malicious but not destructive { c4^$(ly:gulp-file "/etc/passwd") }
‘--jail’ is one way to achieve sandboxing. Another one is running LilyPond in a Docker container.
The ‘--jail’ option 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 usingsudo
.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 comprises 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
, 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 allows 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 supernotation privileges (which, of course, it loses immediately), possibly usingsudo
. It is also good practice 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. See LilyPond in chroot jail for more.
-
-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
Progress messages, warnings, errors and further execution information. This is the default.
-
DEBUG
All possible messages, including verbose debug output.
-
-
-o
,--output=
file -
-o
,--output=
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 is added (e.g., ‘.pdf’ for PDF) in both cases.
-
-O
,--pspdfopt=
key -
Set the PS/PDF output optimization to key. Possible values are:
-
size
Generate a very small PS/EPS/PDF document. This is the default.
Using this value is equivalent to setting LilyPond’s Scheme command-line options
-dmusic-font-encodings='#f'
and-dgs-never-embed-fonts='#f'
.-
TeX
Produce files that are optimized for inclusion in pdfTeX, LuaTeX, or XeTeX documents.
Using this value is equivalent to setting LilyPond’s Scheme command-line options
-dmusic-font-encodings='#t'
and-dgs-never-embed-fonts='#f'
.-
TeX-GS
If you want to include more than one PDF generated by LilyPond in a TeX document, use this option and postprocess the PDF generated by TeX with Ghostscript.
Using this value is equivalent to setting LilyPond’s Scheme command-line options
-dmusic-font-encodings='#t'
and-dgs-never-embed-fonts='#t'
.
-
-
--ps
Generate PostScript. This option is equivalent to
-fps
.-
--png
Generate pictures of each page, in PNG format. This option is equivalent to
-fpng
.The resolution of the image may be set to N DPI with
-dresolution=N
-
--pdf
Generate PDF. This is the default, being equivalent to
-fpdf
.-
-s
,--silent
Show no progress, only error messages. This is equivalent to
-lERROR
.-
--svg
Generate SVG files for each page. This option is equivalent to
-fsvg
.-
-v
,--version
Show version information.
-
-V
,--verbose
Be verbose: show full paths of all files read, give timing information, etc. It is equivalent to
-lDEBUG
.-
-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 >> ] |
[ < Invoking lilypond ] | [ Up : Command-line usage ] | [ Advanced command-line options for LilyPond > ] |