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