<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- header_tag -->
<html lang="en">
<head>
<title>Command line options - GNU LilyPond program usage</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="description" content="GNU LilyPond program usage">
<meta name="generator" content="makeinfo 4.11">
<link title="Top" rel="start" href="index.es.html#Top">
<link rel="up" href="Command_002dline-usage.es.html#Command_002dline-usage" title="Command-line usage">
<link rel="prev" href="Invoking-lilypond.es.html#Invoking-lilypond" title="Invoking lilypond">
<link rel="next" href="Environment-variables.es.html#Environment-variables" title="Environment variables">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
Copyright (C) 1999--2007 by the authors
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.1 or any later version published by the Free Software
Foundation; with no Invariant Sections. A copy of the license is
included in the section entitled ``GNU Free Documentation
License''.
-->
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
pre.display { font-family:inherit }
pre.format { font-family:inherit }
pre.smalldisplay { font-family:inherit; font-size:smaller }
pre.smallformat { font-family:inherit; font-size:smaller }
pre.smallexample { font-size:smaller }
pre.smalllisp { font-size:smaller }
span.sc { font-variant:small-caps }
span.roman { font-family:serif; font-weight:normal; }
span.sansserif { font-family:sans-serif; font-weight:normal; }
hr { border:0; height:1; color: #000000; background-color: #000000; }
/* hr {
border: none;
height: 1px;
color: #666666;
background-color: #666666;
}
body {
border-left: 1px solid #666666;
border-right: 1px solid #666666;
color: #332d28;
margin-right: auto;
margin-left: auto;
width: 60em;
list-style-type: square;
font-family: Arial,Helvetica,sans-serif;
padding-right: 1em;
padding-left: 1em;
}
a {
border-bottom: 1px dashed #344242;
text-decoration: none;
color: #344242;
}
a:link {
text-decoration: none;
}
a:visited {
border-bottom: 1px dashed #666666;
color: #666666;
}
a:active {
border-bottom: 1px solid #00cccc;
color: #00cccc;
}
a:hover {
border-bottom: 1px solid #1d7b85;
color: #1d7b85;
}
blockquote {
border: 1px solid #cccccc;
padding: 3px;
width: 40em;
}
.node {
border-left: 1px solid #666666;
margin: -0.5em 0px 1em;
padding: 2px 1px 0px;
font-style: italic;
}
.node a {
border: none;
text-decoration: underline;
font-style: normal;
font-weight: bold;
}
.verbatim {
font-family: "Courier New",Courier,monospace;
}
.unnumberedsubsubsec {
font-size: large;
color: #1d7b85;
}
.subsubheading {
font-size: large;
color: #3b220d;
}
.contents {
border: 1px dashed #339999;
margin: 3px 2em;
list-style-type: square;
padding-right: 1em;
width: 40em;
background-color: #fcfff9;
}
.contents a {
border-bottom: 1px dashed #423d34;
text-decoration: none;
color: #423d34;
}
.contents a:visited {
border-bottom: 1px dashed #666666;
color: #666666;
}
.contents a:active {
border-bottom: 1px solid #f0d86d;
color: #f0d86d;
}
.contents a:hover {
border-bottom: 1px solid #3b220d;
color: #3b220d;
}
.menu {
border-left: 1px dashed #339999;
margin: 3px 2em 1em;
list-style-type: square;
padding-left: 1.4em;
width: 40em;
}
.unnumbered {
}
h2 {
font-size: x-large;
color: #1d7b85;
}
*/
--></style>
</head>
<BODY BGCOLOR=WHITE TEXT=BLACK>
<div class="node">
<p>
<a name="Command-line-options"></a>
Next: <a rel="next" accesskey="n" href="Environment-variables.es.html#Environment-variables">Environment variables</a>,
Previous: <a rel="previous" accesskey="p" href="Invoking-lilypond.es.html#Invoking-lilypond">Invoking lilypond</a>,
Up: <a rel="up" accesskey="u" href="Command_002dline-usage.es.html#Command_002dline-usage">Command-line usage</a>
<hr>
</div>
<h4 class="subsection">3.2.2 Command line options</h4>
<p>The following options are supported:
<dl>
<dt><code>-e,--evaluate=</code><var>expr</var><dd>Evaluate the Scheme <var>expr</var> before parsing any <samp><span class="file">.ly</span></samp> files.
Multiple <code>-e</code> options may be given, they will be evaluated
sequentially.
<p>The expression will be evaluated in the <code>guile-user</code> module, so
if you want to use definitions in <var>expr</var>, use
<pre class="example"> lilypond -e '(define-public a 42)'
</pre>
<p class="noindent">on the command-line, and include
<pre class="example"> #(use-modules (guile-user))
</pre>
<p class="noindent">at the top of the <code>.ly</code> file.
<br><dt><code>-f,--format=</code><var>format</var><dd>which formats should be written. Choices for <code>format</code> are
<code>svg</code>, <code>ps</code>, <code>pdf</code>, <code>png</code>, <code>tex</code>, <code>dvi</code>.
<p>Example: <code>lilypond -fpng filename.ly</code>
<br><dt><code>-d,--define-default=</code><var>var</var><code>=</code><var>val</var><dd>This sets the internal program option <var>var</var> to the Scheme value
<var>val</var>. If <var>val</var> is not supplied, then <var>#t</var> is used. To
switch off an option, <code>no-</code> may be prefixed to <var>var</var>, e.g.
<p><a name="index-point-and-click_002c-command-line-17"></a>
<pre class="example"> -dno-point-and-click
</pre>
<p class="noindent">is the same as
<pre class="example"> -dpoint-and-click='#f'
</pre>
<p>Here are a few interesting options.
<dl>
<dt>‘<samp><span class="samp">help</span></samp>’<dd>Running <code>lilypond -dhelp</code> will print all of the <code>-d</code> options
available.
<br><dt>‘<samp><span class="samp">paper-size</span></samp>’<dd>This option sets the default paper-size,
<pre class="example"> -dpaper-size=\"letter\"
</pre>
<p class="noindent">Note that the string must be enclosed in escaped quotes ( <code>\"</code> ).
<br><dt>‘<samp><span class="samp">safe</span></samp>’<dd>Do not trust the <code>.ly</code> input.
<p>When LilyPond formatting is available through a web server, either the
<code>--safe</code> or the <code>--jail</code> option <b>MUST</b> be passed. The
<code>--safe</code> option will prevent inline Scheme code from wreaking
havoc, for example
<blockquote>
<pre class="verbatim">
#(system "rm -rf /")
{
c4^#(ly:export (ly:gulp-file "/etc/passwd"))
}
</pre>
</blockquote>
<p>The <code>-dsafe</code> option works by evaluating in-line Scheme
expressions in a special safe module. This safe module is derived from
GUILE <samp><span class="file">safe-r5rs</span></samp> module, but adds a number of functions of the
LilyPond API. These functions are listed in <samp><span class="file">scm/safe-lily.scm</span></samp>.
<p>In addition, safe mode disallows <code>\include</code> directives and
disables the use of backslashes in TeX strings.
<p>In safe mode, it is not possible to import LilyPond variables
into Scheme.
<p>safe does <em>not</em> 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.
<p>The safe mode will prevent many useful LilyPond snippets from being
compiled. The <code>--jail</code> is a more secure alternative, but
requires more work to set up.
<br><dt>‘<samp><span class="samp">backend</span></samp>’<dd>the output format to use for the back-end. Choices for <code>format</code> are
<dl>
<dt><code>tex</code><dd>for TeX output, to be processed with LaTeX. If present, the file
<samp><span class="file">file.textmetrics</span></samp> is read to determine text extents.
<br><dt><code>texstr</code><dd>dump text strings to <samp><span class="file">.texstr</span></samp> file, which can be run through
(La)TeX, resulting in a <code>.textmetrics</code> file, which contains the
extents of strings of text. <strong>Warning:</strong> this functionality is
currently missing due to heavy restructuring of the source code.
<br><dt><code>ps</code><dd> for PostScript.
<a name="index-PostScript-output-18"></a>
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.
<br><dt><code>eps</code><dd> for encapsulated PostScript. This dumps every page (system) as a separate
<samp><span class="file">EPS</span></samp> file, without fonts, and as one collated <samp><span class="file">EPS</span></samp> file with
all pages (systems) including fonts.
<p>This mode is used by default by lilypond-book.
<br><dt><code>svg</code><dd> for SVG (Scalable Vector Graphics). This dumps every page as a separate
<samp><span class="file">SVG</span></samp> file, with embedded fonts.
<a name="index-SVG-_0028Scalable-Vector-Graphics_0029-19"></a> 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 <a href="http://www.inkscape.org">Inkscape</a>
(version 0.42 or later), after copying the OTF fonts in directory
<samp><span class="file">PATH/TO/share/lilypond/VERSION/fonts/otf/</span></samp> to <samp><span class="file">~/.fonts/</span></samp>.
<br><dt><code>scm</code><dd> for a dump of the raw, internal Scheme-based drawing commands.
<a name="index-Scheme-dump-20"></a></dl>
<p>Example: <code>lilypond -dbackend=svg filename.ly</code>
<p><a name="index-output-format_002c-setting-21"></a>
<br><dt>‘<samp><span class="samp">preview</span></samp>’<dd>Generate an output file containing the titles and the first system
<br><dt>‘<samp><span class="samp">print-pages</span></samp>’<dd>Generate the full pages, the default. <code>-dno-print-pages</code> is
useful in combination with <code>-dpreview</code>.
</dl>
<br><dt><code>-h,--help</code><dd>Show a summary of usage.
<br><dt><code>-H,--header=FIELD</code><dd>Dump a header field to file BASENAME.FIELD
<br><dt><code>--include, -I=</code><var>directory</var><dd>Add <var>directory</var> to the search path for input files.
<a name="index-file-searching-22"></a><a name="index-search-path-23"></a>
<br><dt><code>-i,--init=</code><var>file</var><dd>Set init file to <var>file</var> (default: <samp><span class="file">init.ly</span></samp>).
<br><dt><code>-o,--output=</code><var>FILE</var><dd>Set the default output file to <var>FILE</var>. The appropriate
suffix will be added (ie <code>.pdf</code> for pdf, <code>.tex</code>
for tex, etc).
<br><dt><code>--ps</code><dd>Generate PostScript.
<br><dt><code>--dvi</code><dd>Generate DVI files. In this case, the TeX backend should be
specified, i.e., <code>-dbackend=tex</code>.
<br><dt><code>--png</code><dd>Generate pictures of each page, in PNG format. This implies
<code>--ps</code>. The resolution in DPI of the image may be set with
<pre class="example"> -dresolution=110
</pre>
<br><dt><code>--pdf</code><dd>Generate PDF. This implies <code>--ps</code>.
<br><dt><code>-j,--jail=</code><var>user</var><code>,</code><var>group</var><code>,</code><var>jail</var><code>,</code><var>dir</var><dd>Run <samp><span class="command">lilypond</span></samp> in a chroot jail.
<p>The <code>--jail</code> option provides a more flexible alternative to
<code>--safe</code> when LilyPond formatting is available through a web
server or whenever LilyPond executes externally provided
sources.
<p>The <code>--jail</code> option works by changing the root of <samp><span class="command">lilypond</span></samp> to
<var>jail</var> 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 <var>dir</var>. This setup guarantees that it is not
possible (at least in theory) to escape from the jail. Note that for
<code>--jail</code> to work <samp><span class="command">lilypond</span></samp> must be run as root, which is usually
accomplished in a safe way using <samp><span class="command">sudo</span></samp>.
<p>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
<em>inside the jail</em>. A typical setup comprises the following items:
<dl>
<dt>Setting up a separate filesystem<dd>A separate filesystem should be created for LilyPond, so that it can be
mounted with safe options such as <code>noexec</code>, <code>nodev</code>, and
<code>nosuid</code>. 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.
<br><dt>Setting up a separate user<dd>A separate user and group (say, <code>lily</code>/<code>lily</code>) 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
<var>dir</var>.
<br><dt>Preparing the jail<dd>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., <samp><span class="file">/usr/share/lilypond</span></samp>)
should be copied.
<p>If problems arise, the simplest way to trace them down is to run
LilyPond using <samp><span class="command">strace</span></samp>, which will allow you to determine which
files are missing.
<br><dt>Running LilyPond<dd>In a jail mounted with <code>noexec</code> 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 using <samp><span class="command">sudo</span></samp>. It is a good idea to limit the number of
seconds of CPU time LilyPond can use (e.g., using <samp><span class="command">ulimit
-t</span></samp>), and, if your operating system supports it, the amount of memory
that can be allocated.
</dl>
<br><dt><code>-v,--version</code><dd>Show version information.
<br><dt><code>-V,--verbose</code><dd>Be verbose: show full paths of all files read, and give timing
information.
<br><dt><code>-w,--warranty</code><dd>Show the warranty with which GNU LilyPond comes. (It comes with
<strong>NO WARRANTY</strong>!)
</dl>
<!-- footer_tag --><br><hr>
<div class="node">
<p>
Next: <a rel="next" accesskey="n" href="Environment-variables.es.html#Environment-variables">Environment variables</a>,
Previous: <a rel="previous" accesskey="p" href="Invoking-lilypond.es.html#Invoking-lilypond">Invoking lilypond</a>,
Up: <a rel="up" accesskey="u" href="Command_002dline-usage.es.html#Command_002dline-usage">Command-line usage</a>
</div>
<div style="background-color: #e8ffe8; padding: 2; border: #c0ffc0 1px solid;">
<p>
<font size="-1">
Esta página corresponde a LilyPond-2.11.57 (rama de desarrollo).
<br>
<address>
Informe de los fallos a través de la lista en español <a href="http://es.groups.yahoo.com/group/lilypond-es/">lilypond-es</a>, o en inglés a través de <a href="http://post.gmane.org/post.php?group=gmane.comp.gnu.lilypond.bugs">http://post.gmane.org/post.php?group=gmane.comp.gnu.lilypond.bugs</a>. </address>
<br>
Se agradecen las <a href="http://lilypond.org/web/devel/participating/documentation-adding">sugerencias para la documentación</a>.
</font>
</p>
</div>
</BODY></html>
