Documentation/user/invoking.itexi

   1 @node Invoking LilyPond
   2
   3 @chapter Invoking LilyPond
   4 @cindex Invoking LilyPond
   5 @cindex command line options
   6 @cindex options, command line
   7 @cindex switches
   8
   9 Usage:
  10
  11 @example
  12         lilypond [@var{options}] @var{file}@dots{}
  13 @end example
  14
  15
  16
  17 When invoked with a filename that has no extension, LilyPond will try
  18 to add @file{.ly} as an extension first.  To have LilyPond read from
  19 stdin, use a dash @code{-} for @var{file}.
  20
  21 When LilyPond processes @file{filename.ly} it will produce
  22 @file{filename.tex} as output (or @file{filename.ps} for PostScript
  23 output).  If @file{filename.ly} contains more than one @code{\score}
  24 block, then LilyPond will output the rest in numbered files, starting
  25 with @file{filename-1.tex}.  Several files can be specified; they will
  26 each be processed independently.  @footnote{The status of GUILE is not
  27 reset across invocations, so be careful not to change any default
  28 settings from within Scheme .}
  29
  30 @section Command line options
  31
  32 The following options are supported:
  33
  34 @table @code
  35
  36 @item -e,--evaluate=@var{code}
  37   Evaluates the Scheme @var{code} before parsing @file{.ly}
  38 files. Multiple @code{-e} options may be given. They will be evaluated
  39 sequentially.
  40
  41 @item -f,--format=@var{format} Output format for sheet music. Choices
  42 are @code{tex} (for @TeX{} output, to be processed with plain @TeX{},
  43 or through ly2dvi), @code{pdftex} for PDF@TeX{} input, @code{ps} (for
  44 PostScript), @code{scm} (for a Scheme dump), and @code{as} (for
  45 ASCII-art).
  46
  47 Unless you have special requirements, you should use @TeX{}
  48 output. All other options are experimental.
  49 @item -h,--help
  50 Show a summary of usage.
  51 @item --include, -I=@var{directory}
  52 Add @var{directory} to the search path for input files.
  53 @cindex file searching
  54 @cindex search path
  55 @item -i,--init=@var{file}
  56 Set init file to @var{file} (default: @file{init.ly}).
  57 @item -m,--no-paper
  58 @cindex MIDI
  59 Disable @TeX{} output. If you have a @code{\midi} definition midi output
  60 will be generated.
  61 @item -M,--dependencies
  62 Output rules to be included in Makefile.
  63 @item -o,--output=@var{FILE}
  64 Set the default output file to @var{FILE}.
  65 @item -s,--safe
  66 Disallow untrusted @code{\include} directives, in-line
  67 Scheme evaluation, backslashes in @TeX{}, code.
  68
  69 @strong{WARNING}: the @code{--safe} option has not been reviewed for a
  70 long time. Do not rely on it for automatic invocation (e.g. over the
  71 web). Volunteers are welcome to do a new audit.
  72 @item -v,--version
  73 Show version information
  74 @item -V,--verbose
  75 Be verbose: show full paths of all  files read, and give timing
  76 information.
  77
  78 @item -w,--warranty
  79 Show the warranty with which GNU LilyPond comes. (It comes with
  80 @strong{NO WARRANTY}!)
  81 @end table
  82
  83 @section Environment variables
  84
  85
  86 For processing both the @TeX{} and the PostScript output, you must
  87 have appropriate environment variables set.  Scripts to do this are
  88 included in @file{buildscripts/out/lilypond-profile} (for sh shells)
  89 and @file{buildscripts/out/lilypond-login} (for C-shells), and should
  90 normally be sourced as part of your login process. If these scripts
  91 are not run from the system wide login process, then you must run it
  92 yourself.
  93
  94 @cindex installing LilyPond
  95
  96 If you use sh, bash, or a similar shell, then add the following to
  97 your @file{.profile}
  98 @example
  99         . lilypond-profile
 100 @end example
 101
 102 If you use csh, tcsh or a similar shell, then add the following to
 103 your @file{~/.login}
 104 @example
 105         source lilypond-login
 106 @end example
 107
 108 These scripts set the following variables
 109 @table @code
 110 @item TEXMF
 111 This is to make sure that @TeX{} and lilypond find data files (among
 112 others @file{.tex}, @file{.mf} and @file{.tfm}). A typical setting would be
 113 @example
 114 @{/usr/share/lilypond/1.6.0,@{!!/usr/share/texmf@}@}
 115 @end example
 116
 117 you have to set @code{TEXMF} to point to the lilypond data
 118 file tree.
 119
 120 @item GS_LIB
 121 For processing PostScript output (obtained with
 122 @code{-f ps}) with Ghostscript you have to set @code{GS_LIB} to
 123 point to the directory containing LilyPond PS files.
 124
 125 @item GS_FONTPATH
 126 For processing PostScript output (obtained with
 127 @code{-f ps}) with Ghostscript you have to set @code{GS_FONTPATH} to
 128 point to the directory containing LilyPond PFA files.
 129
 130 When you print direct PS output, remember to send the PFA files to the
 131 printer as well.
 132 @end table
 133
 134
 135 @cindex ghostscript
 136 @cindex PostScript
 137 @cindex GS_FONTPATH
 138 @cindex GS_LIB
 139 @cindex TEXMF
 140 @cindex printing postscript
 141
 142 The LilyPond binary itself recognizes the following environment variables
 143 @table @code
 144 @item LILYPONDPREFIX
 145 This specifies a directory where locale messages and
 146 data files will be looked up by default. The directory should contain
 147 subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
 148
 149 @item LANG
 150 This selects the language for the warning messages of LilyPond.
 151 @end table
 152
 153 @cindex LANG
 154 @cindex LILYPONDPREFIX
 155
 156