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