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{OPTION}@dots{} @var{FILE}@dots{}
  13 @end example
  14
  15 To have LilyPond read from stdin, use a dash @code{-} for @var{FILE}.
  16
  17 @unnumberedsec Options
  18
  19 @table @code
  20
  21 @item -e,--evaluate=@var{code}
  22   Evaluates the Scheme @var{code} before parsing @file{.ly}
  23 files. Multiple @code{-e} options may be given. They will be evaluated
  24 sequentially.
  25
  26 @item -f,--format=@var{format}
  27 Output format for sheet music. Choices are @code{tex} (for @TeX{}
  28 output), @code{pdftex} for PDF@TeX{} input, @code{ps} (for PostScript), @code{scm} (for a Scheme
  29 dump), and @code{as} (for ASCII-art).
  30
  31 @c TODO: TFMFONTS
  32
  33 For processing both the @TeX{} and the PostScript output, you must have
  34 appropriate environment variables set.  For @TeX{}, you have to set
  35 @code{MFINPUTS} and @code{TEXINPUTS} to point to the directory
  36 containing LilyPond metafont and .tex files.  For processing PostScript
  37 output with Ghostscript you have to set @code{GS_FONTPATH} to point to
  38 the directory containing LilyPond PFA files.
  39
  40 Scripts to do this are included in
  41 @file{buildscripts/out/lilypond-profile} (for sh shells) and
  42 @file{buildscripts/out/lilypond-login} (for C-shells), and should
  43 normally be run as part of your login process.
  44
  45
  46 @item -h,--help
  47 Show a summary of usage.
  48 @item --include, -I=@var{directory}
  49 Add @var{directory} to the search path for input files.
  50 @cindex file searching
  51 @cindex search path
  52 @item -i,--init=@var{file}
  53 Set init file to @var{file} (default: @file{init.ly}).
  54 @item -m,--no-paper
  55 @cindex MIDI
  56 Disable @TeX{} output. If you have a @code{\midi} definition midi output
  57 will be generated.
  58 @item -M,--dependencies
  59 Output rules to be included in Makefile.
  60 @item -o,--output=@var{FILE}
  61 Set the default output file to @var{FILE}.
  62 @item -s,--safe
  63 Disallow untrusted @code{\include} directives, in-line
  64 Scheme evaluation, backslashes in @TeX{}, code.
  65
  66 @strong{WARNING}: the @code{--safe} option has not been reviewed for a
  67 long time; do not rely on it for automatic invocation (e.g. over the
  68 web). Volunteers are welcome to do a new audit.
  69
  70 @item -v,--version
  71 Show version information
  72 @item -V,--verbose
  73 Be verbose: show full paths of all  files read, and give timing
  74 information.
  75
  76 @item -w,--warranty
  77 Show the warranty with which GNU LilyPond comes. (It comes with
  78 @strong{NO WARRANTY}!)
  79 @end table
  80
  81
  82 When invoked with a filename that has no extension, LilyPond will try to
  83 add @file{.ly} as an extension first.
  84
  85 When LilyPond processes @file{filename.ly} it will produce
  86 @file{filename.tex} as output (or @file{filename.ps} for PostScript
  87 output).  If @file{filename.ly} contains more than one @code{\score}
  88 block, then LilyPond will output the rest in numbered files, starting
  89 with @file{filename-1.tex}.  Several files can be specified; they will
  90 each be processed independently.  @footnote{The status of GUILE is not
  91 reset across invocations, so be careful not to change any default
  92 settings from within Scheme .}
  93
  94 @section Environment variables
  95
  96 @table @code
  97 @item LILYINCLUDE
  98 additional directories for finding lilypond data.  The
  99 format is like the format of @file{PATH}.
 100 @item LILYPONDPREFIX
 101 This specifies a directory where locale messages and
 102 data files will be looked up by default. The directory should contain
 103 subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
 104
 105 @item LANG
 106 selects the language for the warning messages of LilyPond.
 107 @end table
 108
 109