| [ << Running LilyPond ] | [Top][Contents][Index][ ? ] | [ LilyPond-book >> ] | ||
| [ < Invoking lilypond ] | [ Up : Command-line usage ] | [ Environment variables > ] | ||
3.2.2 Command line options for lilypond
The following options are supported:
-
-e,--evaluate=expr Evaluate the Scheme expr before parsing any ‘.ly’ files. Multiple
-eoptions may be given, they will be evaluated sequentially.The expression will be evaluated in the
guile-usermodule, 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
.lyfile.-
-f,--format=format which formats should be written. Choices for
formataresvg,ps,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 -dhelpwill print all of the-doptions 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
.lyinput.When LilyPond formatting is available through a web server, either the
--safeor the--jailoption MUST be passed. The--safeoption will prevent inline Scheme code from wreaking havoc, for example#(system "rm -rf /") { c4^#(ly:export (ly:gulp-file "/etc/passwd")) }The
-dsafeoption 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
\includedirectives and disables the use of backslashes in TeX strings.In safe mode, it is not possible to import LilyPond variables into Scheme.
-dsafedoes 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
--jailis a more secure alternative, but requires more work to set up.- ‘backend’
the output format to use for the back-end. Choices for
formatare-
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 dumps every page as a separate ‘SVG’ file, with embedded fonts. You need a SVG viewer which supports embedded fonts, or a SVG viewer which is able to replace the embedded fonts with OTF fonts. Under UNIX, you may use Inkscape (version 0.42 or later), after copying the OTF fonts from the LilyPond directory (typically ‘/usr/share/lilypond/VERSION/fonts/otf/’) to ‘~/.fonts/’.
-
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
- ‘print-pages’
Generate the full pages, the default.
-dno-print-pagesis 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 -
-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 (e.g.
.pdffor pdf)-
--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
lilypondin a chroot jail.The
--jailoption provides a more flexible alternative to--safewhen LilyPond formatting is available through a web server or whenever LilyPond executes externally provided sources.The
--jailoption works by changing the root oflilypondto 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--jailto worklilypondmust 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
noexecit 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][ ? ] | [ LilyPond-book >> ] | ||
| [ < Invoking lilypond ] | [ Up : Command-line usage ] | [ Environment variables > ] | ||