1087
|
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
2 <HTML>
|
|
3 <HEAD>
|
|
4 <TITLE>Lua 5.2 readme</TITLE>
|
|
5 <LINK REL="stylesheet" TYPE="text/css" HREF="lua.css">
|
|
6 <META HTTP-EQUIV="content-type" CONTENT="text/html; charset=iso-8859-1">
|
|
7 <STYLE TYPE="text/css">
|
|
8 blockquote, .display {
|
|
9 border: solid #a0a0a0 2px ;
|
|
10 padding: 1em ;
|
|
11 margin: 0px ;
|
|
12 }
|
|
13
|
|
14 .display {
|
|
15 word-spacing: 0.25em ;
|
|
16 }
|
|
17
|
|
18 dl.display dd {
|
|
19 padding-bottom: 0.2em ;
|
|
20 }
|
|
21
|
|
22 tt, kbd, code {
|
|
23 font-size: 12pt ;
|
|
24 }
|
|
25 </STYLE>
|
|
26 </HEAD>
|
|
27
|
|
28 <BODY>
|
|
29
|
|
30 <HR>
|
|
31 <H1>
|
|
32 <A HREF="http://www.lua.org/"><IMG SRC="logo.gif" ALT="Lua" BORDER=0></A>
|
|
33 Welcome to Lua 5.2
|
|
34 </H1>
|
|
35
|
|
36 <P>
|
|
37 <A HREF="#about">about</A>
|
|
38 ·
|
|
39 <A HREF="#install">installation</A>
|
|
40 ·
|
|
41 <A HREF="#changes">changes</A>
|
|
42 ·
|
|
43 <A HREF="#license">license</A>
|
|
44 ·
|
|
45 <A HREF="contents.html">reference manual</A>
|
|
46
|
|
47 <H2><A NAME="about">About Lua</A></H2>
|
|
48
|
|
49 <P>
|
|
50 Lua is a powerful, fast, lightweight, embeddable scripting language
|
|
51 developed by a
|
|
52 <A HREF="http://www.lua.org/authors.html">team</A>
|
|
53 at
|
|
54 <A HREF="http://www.puc-rio.br/">PUC-Rio</A>,
|
|
55 the Pontifical Catholic University of Rio de Janeiro in Brazil.
|
|
56 Lua is
|
|
57 <A HREF="#license">free software</A>
|
|
58 used in many products and projects around the world.
|
|
59
|
|
60 <P>
|
|
61 Lua's
|
|
62 <A HREF="http://www.lua.org/">official web site</A>
|
|
63 provides complete information
|
|
64 about Lua,
|
|
65 including
|
|
66 an
|
|
67 <A HREF="http://www.lua.org/about.html">executive summary</A>
|
|
68 and
|
|
69 updated
|
|
70 <A HREF="http://www.lua.org/docs.html">documentation</A>,
|
|
71 especially the
|
|
72 <A HREF="http://www.lua.org/manual/5.2/">reference manual</A>,
|
|
73 which may differ slightly from the
|
|
74 <A HREF="contents.html">local copy</A>
|
|
75 distributed in this package.
|
|
76
|
|
77 <H2><A NAME="install">Installing Lua</A></H2>
|
|
78
|
|
79 <P>
|
|
80 Lua is distributed in
|
|
81 <A HREF="http://www.lua.org/ftp/">source</A>
|
|
82 form.
|
|
83 You need to build it before using it.
|
|
84 Building Lua should be straightforward
|
|
85 because
|
|
86 Lua is implemented in pure ANSI C and compiles unmodified in all known
|
|
87 platforms that have an ANSI C compiler.
|
|
88 Lua also compiles unmodified as C++.
|
|
89 The instructions given below for building Lua are for Unix-like platforms.
|
|
90 See also
|
|
91 <A HREF="#other">instructions for other systems</A>
|
|
92 and
|
|
93 <A HREF="#customization">customization options</A>.
|
|
94
|
|
95 <P>
|
|
96 If you don't have the time or the inclination to compile Lua yourself,
|
|
97 get a binary from
|
|
98 <A HREF="http://lua-users.org/wiki/LuaBinaries">LuaBinaries</A>.
|
|
99 Try also
|
|
100 <A HREF="http://luaforwindows.luaforge.net/">Lua for Windows</A>,
|
|
101 an easy-to-use distribution of Lua that includes many useful libraries.
|
|
102
|
|
103 <H3>Building Lua</H3>
|
|
104
|
|
105 <P>
|
|
106 In most Unix-like platforms, simply do "<KBD>make</KBD>" with a suitable target.
|
|
107 Here are the details.
|
|
108
|
|
109 <OL>
|
|
110 <LI>
|
|
111 Open a terminal window and move to
|
|
112 the top-level directory, which is named <TT>lua-5.2.1</TT>.
|
|
113 The Makefile there controls both the build process and the installation process.
|
|
114 <P>
|
|
115 <LI>
|
|
116 Do "<KBD>make</KBD>" and see if your platform is listed.
|
|
117 The platforms currently supported are:
|
|
118 <P>
|
|
119 <P CLASS="display">
|
|
120 aix ansi bsd freebsd generic linux macosx mingw posix solaris
|
|
121 </P>
|
|
122 <P>
|
|
123 If your platform is listed, just do "<KBD>make xxx</KBD>", where xxx
|
|
124 is your platform name.
|
|
125 <P>
|
|
126 If your platform is not listed, try the closest one or posix, generic,
|
|
127 ansi, in this order.
|
|
128 <P>
|
|
129 <LI>
|
|
130 The compilation takes only a few moments
|
|
131 and produces three files in the <TT>src</TT> directory:
|
|
132 lua (the interpreter),
|
|
133 luac (the compiler),
|
|
134 and liblua.a (the library).
|
|
135 <P>
|
|
136 <LI>
|
|
137 To check that Lua has been built correctly, do "<KBD>make test</KBD>"
|
|
138 after building Lua. This will run the interpreter and print its version string.
|
|
139 </OL>
|
|
140 <P>
|
|
141 If you're running Linux and get compilation errors,
|
|
142 make sure you have installed the <TT>readline</TT> development package.
|
|
143
|
|
144 <H3>Installing Lua</H3>
|
|
145 <P>
|
|
146 Once you have built Lua, you may want to install it in an official
|
|
147 place in your system. In this case, do "<KBD>make install</KBD>". The official
|
|
148 place and the way to install files are defined in the Makefile. You'll
|
|
149 probably need the right permissions to install files.
|
|
150
|
|
151 <P>
|
|
152 To build and install Lua in one step, do "<KBD>make xxx install</KBD>",
|
|
153 where xxx is your platform name.
|
|
154
|
|
155 <P>
|
|
156 To install Lua locally, do "<KBD>make local</KBD>".
|
|
157 This will create a directory <TT>install</TT> with subdirectories
|
|
158 <TT>bin</TT>, <TT>include</TT>, <TT>lib</TT>, <TT>man</TT>,
|
|
159 and install Lua as listed below.
|
|
160
|
|
161 To install Lua locally, but in some other directory, do
|
|
162 "<KBD>make install INSTALL_TOP=xxx</KBD>", where xxx is your chosen directory.
|
|
163
|
|
164 <DL CLASS="display">
|
|
165 <DT>
|
|
166 bin:
|
|
167 <DD>
|
|
168 lua luac
|
|
169 <DT>
|
|
170 include:
|
|
171 <DD>
|
|
172 lua.h luaconf.h lualib.h lauxlib.h lua.hpp
|
|
173 <DT>
|
|
174 lib:
|
|
175 <DD>
|
|
176 liblua.a
|
|
177 <DT>
|
|
178 man/man1:
|
|
179 <DD>
|
|
180 lua.1 luac.1
|
|
181 </DL>
|
|
182
|
|
183 <P>
|
|
184 These are the only directories you need for development.
|
|
185 If you only want to run Lua programs,
|
|
186 you only need the files in bin and man.
|
|
187 The files in include and lib are needed for
|
|
188 embedding Lua in C or C++ programs.
|
|
189
|
|
190 <H3><A NAME="customization">Customization</A></H3>
|
|
191 <P>
|
|
192 Three kinds of things can be customized by editing a file:
|
|
193 <UL>
|
|
194 <LI> Where and how to install Lua — edit <TT>Makefile</TT>.
|
|
195 <LI> How to build Lua — edit <TT>src/Makefile</TT>.
|
|
196 <LI> Lua features — edit <TT>src/luaconf.h</TT>.
|
|
197 </UL>
|
|
198
|
|
199 <P>
|
|
200 You don't actually need to edit the Makefiles because you may set the
|
|
201 relevant variables in the command line when invoking make.
|
|
202 Nevertheless, it's probably best to edit and save the Makefiles to
|
|
203 record the changes you need.
|
|
204
|
|
205 <P>
|
|
206 On the other hand, if you need to customize some Lua features, you'll need
|
|
207 to edit <TT>src/luaconf.h</TT> before building and installing Lua.
|
|
208 The edited file will be the one installed, and
|
|
209 it will be used by any Lua clients that you build, to ensure consistency.
|
|
210 Further customization is available to experts by editing the Lua sources.
|
|
211
|
|
212 <P>
|
|
213 We strongly recommend that you enable dynamic loading in <TT>src/luaconf.h</TT>.
|
|
214 This is done automatically for all platforms listed above that have
|
|
215 this feature and also for Windows.
|
|
216
|
|
217 <H3><A NAME="other">Building Lua on other systems</A></H3>
|
|
218
|
|
219 <P>
|
|
220 If you're not using the usual Unix tools, then the instructions for
|
|
221 building Lua depend on the compiler you use. You'll need to create
|
|
222 projects (or whatever your compiler uses) for building the library,
|
|
223 the interpreter, and the compiler, as follows:
|
|
224
|
|
225 <DL CLASS="display">
|
|
226 <DT>
|
|
227 library:
|
|
228 <DD>
|
|
229 lapi.c lcode.c lctype.c ldebug.c ldo.c ldump.c lfunc.c lgc.c llex.c
|
|
230 lmem.c lobject.c lopcodes.c lparser.c lstate.c lstring.c ltable.c
|
|
231 ltm.c lundump.c lvm.c lzio.c
|
|
232 lauxlib.c lbaselib.c lbitlib.c lcorolib.c ldblib.c liolib.c
|
|
233 lmathlib.c loslib.c lstrlib.c ltablib.c loadlib.c linit.c
|
|
234 <DT>
|
|
235 interpreter:
|
|
236 <DD>
|
|
237 library, lua.c
|
|
238 <DT>
|
|
239 compiler:
|
|
240 <DD>
|
|
241 library, luac.c
|
|
242 </DL>
|
|
243
|
|
244 <P>
|
|
245 To use Lua as a library in your own programs you'll need to know how to
|
|
246 create and use libraries with your compiler. Moreover, to dynamically load
|
|
247 C libraries for Lua you'll need to know how to create dynamic libraries
|
|
248 and you'll need to make sure that the Lua API functions are accessible to
|
|
249 those dynamic libraries — but <EM>don't</EM> link the Lua library
|
|
250 into each dynamic library. For Unix, we recommend that the Lua library
|
|
251 be linked statically into the host program and its symbols exported for
|
|
252 dynamic linking; <TT>src/Makefile</TT> does this for the Lua interpreter.
|
|
253 For Windows, we recommend that the Lua library be a DLL.
|
|
254
|
|
255 <P>
|
|
256 As mentioned above, you may edit <TT>src/luaconf.h</TT> to customize
|
|
257 some features before building Lua.
|
|
258
|
|
259 <H2><A NAME="changes">Changes since Lua 5.1</A></H2>
|
|
260
|
|
261 <P>
|
|
262 Here are the main changes introduced in Lua 5.2.
|
|
263 The
|
|
264 <A HREF="contents.html">reference manual</A>
|
|
265 lists the
|
|
266 <A HREF="manual.html#8">incompatibilities</A> that had to be introduced.
|
|
267
|
|
268 <H3>Main changes</H3>
|
|
269 <UL>
|
|
270 <LI> yieldable pcall and metamethods
|
|
271 <LI> new lexical scheme for globals
|
|
272 <LI> ephemeron tables
|
|
273 <LI> new library for bitwise operations
|
|
274 <LI> light C functions
|
|
275 <LI> emergency garbage collector
|
|
276 <LI> <CODE>goto</CODE> statement
|
|
277 <LI> finalizers for tables
|
|
278 </UL>
|
|
279
|
|
280 Here are the other changes introduced in Lua 5.2:
|
|
281 <H3>Language</H3>
|
|
282 <UL>
|
|
283 <LI> no more fenv for threads or functions
|
|
284 <LI> tables honor the <CODE>__len</CODE> metamethod
|
|
285 <LI> hex and <CODE>\z</CODE> escapes in strings
|
|
286 <LI> support for hexadecimal floats
|
|
287 <LI> order metamethods work for different types
|
|
288 <LI> no more verification of opcode consistency
|
|
289 <LI> hook event "tail return" replaced by "tail call"
|
|
290 <LI> empty statement
|
|
291 <LI> <CODE>break</CODE> statement may appear in the middle of a block
|
|
292 </UL>
|
|
293
|
|
294 <H3>Libraries</H3>
|
|
295 <UL>
|
|
296 <LI> arguments for function called through <CODE>xpcall</CODE>
|
|
297 <LI> optional 'mode' argument to load and loadfile (to control binary x text)
|
|
298 <LI> optional 'env' argument to load and loadfile (environment for loaded chunk)
|
|
299 <LI> <CODE>loadlib</CODE> may load libraries with global names (RTLD_GLOBAL)
|
|
300 <LI> new function <CODE>package.searchpath</CODE>
|
|
301 <LI> modules receive their paths when loaded
|
|
302 <LI> optional base in <CODE>math.log</CODE>
|
|
303 <LI> optional separator in <CODE>string.rep</CODE>
|
|
304 <LI> <CODE>file:write</CODE> returns <CODE>file</CODE>
|
|
305 <LI> closing a pipe returns exit status
|
|
306 <LI> <CODE>os.exit</CODE> may close state
|
|
307 <LI> new metamethods <CODE>__pairs</CODE> and <CODE>__ipairs</CODE>
|
|
308 <LI> new option 'isrunning' for <CODE>collectgarbage</CODE> and <CODE>lua_gc</CODE>
|
|
309 <LI> frontier patterns
|
|
310 <LI> <CODE>\0</CODE> in patterns
|
|
311 <LI> new option <CODE>*L</CODE> for <CODE>io.read</CODE>
|
|
312 <LI> options for <CODE>io.lines</CODE>
|
|
313 <LI> <CODE>debug.getlocal</CODE> can access function varargs
|
|
314 </UL>
|
|
315
|
|
316 <H3>C API</H3>
|
|
317 <UL>
|
|
318 <LI> main thread predefined in the registry
|
|
319 <LI> new functions
|
|
320 <CODE>lua_absindex</CODE>,
|
|
321 <CODE>lua_arith</CODE>,
|
|
322 <CODE>lua_compare</CODE>,
|
|
323 <CODE>lua_copy</CODE>,
|
|
324 <CODE>lua_len</CODE>,
|
|
325 <CODE>lua_rawgetp</CODE>,
|
|
326 <CODE>lua_rawsetp</CODE>,
|
|
327 <CODE>lua_upvalueid</CODE>,
|
|
328 <CODE>lua_upvaluejoin</CODE>,
|
|
329 <CODE>lua_version</CODE>.
|
|
330 <LI> new functions
|
|
331 <CODE>luaL_checkversion</CODE>,
|
|
332 <CODE>luaL_setmetatable</CODE>,
|
|
333 <CODE>luaL_testudata</CODE>,
|
|
334 <CODE>luaL_tolstring</CODE>.
|
|
335 <LI> <CODE>lua_pushstring</CODE> and <CODE>pushlstring</CODE> return string
|
|
336 <LI> <CODE>nparams</CODE> and <CODE>isvararg</CODE> available in debug API
|
|
337 <LI> new <CODE>lua_Unsigned</CODE>
|
|
338 </UL>
|
|
339
|
|
340 <H3>Implementation</H3>
|
|
341 <UL>
|
|
342 <LI> max constants per function raised to 2<SUP>26</SUP>
|
|
343 <LI> generational mode for garbage collection (experimental)
|
|
344 <LI> NaN trick (experimental)
|
|
345 <LI> internal (immutable) version of ctypes
|
|
346 <LI> simpler implementation for string buffers
|
|
347 <LI> parser uses much less C-stack space (no more auto arrays)
|
|
348 </UL>
|
|
349
|
|
350 <H3>Lua standalone interpreter</H3>
|
|
351 <UL>
|
|
352 <LI> new <CODE>-E</CODE> option to avoid environment variables
|
|
353 <LI> handling of non-string error messages
|
|
354 </UL>
|
|
355
|
|
356 <H2><A NAME="license">License</A></H2>
|
|
357 <A HREF="http://www.opensource.org/docs/definition.php">
|
|
358 <IMG SRC="osi-certified-72x60.png" ALIGN="right" BORDER="0" ALT="[osi certified]" STYLE="padding-left: 30px ;">
|
|
359 </A>
|
|
360
|
|
361 <P>
|
|
362 Lua is free software distributed under the terms of the
|
|
363 <A HREF="http://www.opensource.org/licenses/mit-license.html">MIT license</A>
|
|
364 reproduced below;
|
|
365 it may be used for any purpose, including commercial purposes,
|
|
366 at absolutely no cost without having to ask us.
|
|
367
|
|
368 The only requirement is that if you do use Lua,
|
|
369 then you should give us credit by including the appropriate copyright notice somewhere in your product or its documentation.
|
|
370
|
|
371 For details, see
|
|
372 <A HREF="http://www.lua.org/license.html">this</A>.
|
|
373
|
|
374 <BLOCKQUOTE STYLE="padding-bottom: 0em">
|
|
375 Copyright © 1994–2012 Lua.org, PUC-Rio.
|
|
376
|
|
377 <P>
|
|
378 Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
379 of this software and associated documentation files (the "Software"), to deal
|
|
380 in the Software without restriction, including without limitation the rights
|
|
381 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
382 copies of the Software, and to permit persons to whom the Software is
|
|
383 furnished to do so, subject to the following conditions:
|
|
384
|
|
385 <P>
|
|
386 The above copyright notice and this permission notice shall be included in
|
|
387 all copies or substantial portions of the Software.
|
|
388
|
|
389 <P>
|
|
390 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
391 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
392 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
393 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
394 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
395 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
|
|
396 THE SOFTWARE.
|
|
397 </BLOCKQUOTE>
|
|
398 <P>
|
|
399
|
|
400 <HR>
|
|
401 <SMALL CLASS="footer">
|
|
402 Last update:
|
|
403 Tue May 29 21:57:51 BRT 2012
|
|
404 </SMALL>
|
|
405 <!--
|
|
406 Last change: revised for Lua 5.2.1
|
|
407 -->
|
|
408
|
|
409 </BODY>
|
|
410 </HTML>
|