doc/luac.html

   1 <!-- luac.man,v 1.17 1999/07/07 16:02:07 lhf Exp -->
   2 <HTML>
   3 <HEAD>
   4 <TITLE>LUAC man page</TITLE>
   5 </HEAD>
   6
   7 <BODY BGCOLOR="#FFFFFF">
   8
   9 <H1>NAME</H1>
  10 luac - Lua compiler
  11 <H1>SYNOPSIS</H1>
  12 <B>luac</B>
  13 [
  14 <I>options</I>
  15 ] [
  16 <I>filenames</I>
  17 ]
  18 <H1>DESCRIPTION</H1>
  19 <B>luac</B>
  20 is the Lua compiler.
  21 It translates programs written in the Lua programming language
  22 into binary files that can be loaded and executed with
  23 <B>lua_dofile</B>
  24 in C or with
  25 <B>dofile</B>
  26 in Lua.
  27 <P>
  28 The main advantages of pre-compiling chunks are:
  29 faster loading,
  30 protecting source code from user changes,
  31 and
  32 off-line syntax error detection.
  33 The binary files created by
  34 <B>luac</B>
  35 are portable to all architectures.
  36 <P>
  37 Pre-compiling does not imply faster execution
  38 because in Lua chunks are always compiled into bytecodes before being executed.
  39 <B>luac</B>
  40 simply allows those bytecodes to be saved in a file for later execution.
  41 <P>
  42 <B>luac</B>
  43 produces a single output file containing the bytecodes
  44 for all source files given.
  45 By default,
  46 the output file is named
  47 <B>luac.out</B>,
  48 but you can change this with the
  49 <B>-o</B>
  50 option.
  51 <P>
  52 You can use
  53 <B>"-"</B>
  54 to indicate
  55 <I>stdin</I>
  56 as a source file.
  57 <P>
  58 <B>luac</B>
  59 can also load and list binary files with the
  60 <B>-u</B>
  61 option.
  62 <P>
  63 Binary files produced by differents runs of
  64 <B>luac</B>
  65 (even in different machines)
  66 can be combined into one large file,
  67 using
  68 <B>cat</B>(1).
  69 The result is still a valid binary file
  70 and can be loaded with a single call to
  71 <B>lua_dofile</B>
  72 or
  73 <B>dofile</B>.
  74 <P>
  75 The internal format of the binary files produced by
  76 <B>luac</B>
  77 may change when a new version of Lua is released.
  78 We try to maintain compatibility even for binary files,
  79 but sometimes it cannot be done.
  80 So,
  81 save the source files of all Lua programs that you precompile.
  82 <P>
  83 <H1>OPTIONS</H1>
  84 Options must be separate.
  85 <P>
  86 <B>-c</B>
  87 compile (this is the default).
  88 <P>
  89 <B>-u</B>
  90 undump, i.e., load and list the given binary files.
  91 If no files are given, then luac undumps
  92 <B>luac.out</B>.
  93 Listing a binary file is useful to learn Lua's virtual machine.
  94 Listing is also useful to test the integrity of binary files:
  95 corrupted files will probably generate errors when undumped.
  96 To test without listing, use
  97 <B>-q</B>.
  98 For a thourough integrity test,
  99 use
 100 <B>-t</B>.
 101 <P>
 102 <B>-d</B>
 103 turn debugging on.
 104 Individual chunks may
 105 still control the generation of debug information with
 106 $debug and $nodebug.
 107 If debugging is on, then listings show the names of the local variables.
 108 <P>
 109 <B>-D "</B><I>name"</I>
 110 predefine symbol
 111 <I>name</I>
 112 for conditional compilation.
 113 By default,
 114 <B>luac</B>
 115 does
 116 <I>not</I>
 117 predefine any symbols,
 118 not even the built-in functions.
 119 <P>
 120 <B>-l</B>
 121 produce a listing of the compiled bytecode for Lua's virtual machine.
 122 This is the default when undumping.
 123 <P>
 124 <B>-n</B>
 125 Save numbers in native format.
 126 By default,
 127 numbers are saved in text form,
 128 for maximum portability.
 129 Binary files with numbers in native format are slightly faster to load,
 130 but are not completely portable.
 131 <P>
 132 <B>-o "</B><I>filename"</I>
 133 output to
 134 <I>filename</I>,
 135 instead of the default
 136 <B>luac.out</B>.
 137 The output file cannot be a source file.
 138 <P>
 139 <B>-O</B>
 140 optimize.
 141 Debug information is removed
 142 and
 143 duplicate constants are coalesced.
 144 <P>
 145 <B>-p</B>
 146 parse sources files but do not generate any output file.
 147 Used mainly for syntax checking.
 148 <P>
 149 <B>-q</B>
 150 quiet; produces no listing.
 151 This is the default when compiling.
 152 <P>
 153 <B>-t</B>
 154 perform a thourough integrity test when undumping.
 155 Code that passes this test is completely safe,
 156 in the sense that it will not break the interpreter.
 157 However,
 158 there is no guarantee that such code does anything sensible.
 159 (None can be given, because the halting problem is unsolvable.)
 160 <P>
 161 <B>-U "</B><I>name"</I>
 162 undefine symbol
 163 <I>name</I>
 164 for conditional compilation.
 165 <P>
 166 <B>-v</B>
 167 print version information.
 168 <P>
 169 <B>-V</B>
 170 verbose;
 171 print the names of the source files as they are processed.
 172 <H1>FILES</H1>
 173 <P>
 174 <B>luac.out</B>
 175 default output file
 176 <H1>SEE ALSO</H1>
 177 <B>lua</B>(1)
 178 <BR>
 179 <I>"Reference Manual of the Programming Language Lua"</I>
 180 <BR>
 181 <A HREF="http://www.tecgraf.puc-rio.br/lua/">http://www.tecgraf.puc-rio.br/lua/</A>
 182 <BR>
 183 "Lua: an extensible extension language",
 184 <I>Software: Practice &amp; Experience</I>
 185 <B>26</B>
 186 #6 (1996) 635-652.
 187 <H1>DIAGNOSTICS</H1>
 188 Error messages should be self explanatory.
 189 <H1>AUTHORS</H1>
 190 L. H. de Figueiredo,
 191 R. Ierusalimschy and
 192 W. Celes
 193 <I>(<A HREF="mailto:lua@tecgraf.puc-rio.br">lua@tecgraf.puc-rio.br</A>)</I>
 194 <!-- EOF -->