1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2<HTML>
3<HEAD>
4<TITLE>Lua 5.4 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">
8blockquote, .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
19dl.display dd {
20 padding-bottom: 0.2em ;
21}
22
23tt, kbd, code {
24 font-size: 12pt ;
25}
26</STYLE>
27</HEAD>
28
29<BODY>
30
31<H1>
32<A HREF="http://www.lua.org/"><IMG SRC="logo.gif" ALT="Lua"></A>
33Welcome to Lua 5.4
34</H1>
35
36<DIV CLASS="menubar">
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</DIV>
47
48<H2><A NAME="about">About Lua</A></H2>
49<P>
50Lua is a powerful, efficient, lightweight, embeddable scripting language
51developed by a
52<A HREF="http://www.lua.org/authors.html">team</A>
53at
54<A HREF="http://www.puc-rio.br/">PUC-Rio</A>,
55the Pontifical Catholic University of Rio de Janeiro in Brazil.
56Lua is
57<A HREF="#license">free software</A>
58used in
59<A HREF="http://www.lua.org/uses.html">many products and projects</A>
60around the world.
61
62<P>
63Lua's
64<A HREF="http://www.lua.org/">official web site</A>
65provides complete information
66about Lua,
67including
68an
69<A HREF="http://www.lua.org/about.html">executive summary</A>
70and
71updated
72<A HREF="http://www.lua.org/docs.html">documentation</A>,
73especially the
74<A HREF="http://www.lua.org/manual/5.4/">reference manual</A>,
75which may differ slightly from the
76<A HREF="contents.html">local copy</A>
77distributed in this package.
78
79<H2><A NAME="install">Installing Lua</A></H2>
80<P>
81Lua is distributed in
82<A HREF="http://www.lua.org/ftp/">source</A>
83form.
84You need to build it before using it.
85Building Lua should be straightforward
86because
87Lua is implemented in pure ANSI C and compiles unmodified in all known
88platforms that have an ANSI C compiler.
89Lua also compiles unmodified as C++.
90The instructions given below for building Lua are for Unix-like platforms,
91such as Linux and Mac OS X.
92See also
93<A HREF="#other">instructions for other systems</A>
94and
95<A HREF="#customization">customization options</A>.
96
97<P>
98If you don't have the time or the inclination to compile Lua yourself,
99get a binary from
100<A HREF="http://lua-users.org/wiki/LuaBinaries">LuaBinaries</A>.
101Try also
102<A HREF="http://luadist.org/">LuaDist</A>,
103a multi-platform distribution of Lua that includes batteries.
104
105<H3>Building Lua</H3>
106<P>
107In most common Unix-like platforms, simply do "<KBD>make</KBD>".
108Here are the details.
109
110<OL>
111<LI>
112Open a terminal window and move to
113the top-level directory, which is named <TT>lua-5.4.1</TT>.
114The <TT>Makefile</TT> there controls both the build process and the installation process.
115<P>
116<LI>
117 Do "<KBD>make</KBD>". The <TT>Makefile</TT> will guess your platform and build Lua for it.
118<P>
119<LI>
120 If the guess failed, do "<KBD>make help</KBD>" and see if your platform is listed.
121 The platforms currently supported are:
122<P>
123<P CLASS="display">
124 guess aix bsd c89 freebsd generic linux linux-readline macosx mingw posix solaris
125</P>
126<P>
127 If your platform is listed, just do "<KBD>make xxx</KBD>", where xxx
128 is your platform name.
129<P>
130 If your platform is not listed, try the closest one or posix, generic,
131 c89, in this order.
132<P>
133<LI>
134The compilation takes only a few moments
135and produces three files in the <TT>src</TT> directory:
136lua (the interpreter),
137luac (the compiler),
138and liblua.a (the library).
139<P>
140<LI>
141 To check that Lua has been built correctly, do "<KBD>make test</KBD>"
142 after building Lua. This will run the interpreter and print its version.
143</OL>
144<P>
145If you're running Linux, try "<KBD>make linux-readline</KBD>" to build the interactive Lua interpreter with handy line-editing and history capabilities.
146If you get compilation errors,
147make sure you have installed the <TT>readline</TT> development package
148(which is probably named <TT>libreadline-dev</TT> or <TT>readline-devel</TT>).
149If you get link errors after that,
150then try "<KBD>make linux-readline MYLIBS=-ltermcap</KBD>".
151
152<H3>Installing Lua</H3>
153<P>
154 Once you have built Lua, you may want to install it in an official
155 place in your system. In this case, do "<KBD>make install</KBD>". The official
156 place and the way to install files are defined in the <TT>Makefile</TT>. You'll
157 probably need the right permissions to install files, and so may need to do "<KBD>sudo make install</KBD>".
158
159<P>
160 To build and install Lua in one step, do "<KBD>make all install</KBD>",
161 or "<KBD>make xxx install</KBD>",
162 where xxx is your platform name.
163
164<P>
165 To install Lua locally after building it, do "<KBD>make local</KBD>".
166 This will create a directory <TT>install</TT> with subdirectories
167 <TT>bin</TT>, <TT>include</TT>, <TT>lib</TT>, <TT>man</TT>, <TT>share</TT>,
168 and install Lua as listed below.
169
170 To install Lua locally, but in some other directory, do
171 "<KBD>make install INSTALL_TOP=xxx</KBD>", where xxx is your chosen directory.
172 The installation starts in the <TT>src</TT> and <TT>doc</TT> directories,
173 so take care if <TT>INSTALL_TOP</TT> is not an absolute path.
174
175<DL CLASS="display">
176<DT>
177 bin:
178<DD>
179 lua luac
180<DT>
181 include:
182<DD>
183 lua.h luaconf.h lualib.h lauxlib.h lua.hpp
184<DT>
185 lib:
186<DD>
187 liblua.a
188<DT>
189 man/man1:
190<DD>
191 lua.1 luac.1
192</DL>
193
194<P>
195 These are the only directories you need for development.
196 If you only want to run Lua programs,
197 you only need the files in <TT>bin</TT> and <TT>man</TT>.
198 The files in <TT>include</TT> and <TT>lib</TT> are needed for
199 embedding Lua in C or C++ programs.
200
201<H3><A NAME="customization">Customization</A></H3>
202<P>
203 Three kinds of things can be customized by editing a file:
204<UL>
205 <LI> Where and how to install Lua — edit <TT>Makefile</TT>.
206 <LI> How to build Lua — edit <TT>src/Makefile</TT>.
207 <LI> Lua features — edit <TT>src/luaconf.h</TT>.
208</UL>
209
210<P>
211 You don't actually need to edit the Makefiles because you may set the
212 relevant variables in the command line when invoking make.
213 Nevertheless, it's probably best to edit and save the Makefiles to
214 record the changes you've made.
215
216<P>
217 On the other hand, if you need to customize some Lua features, you'll need
218 to edit <TT>src/luaconf.h</TT> before building and installing Lua.
219 The edited file will be the one installed, and
220 it will be used by any Lua clients that you build, to ensure consistency.
221 Further customization is available to experts by editing the Lua sources.
222
223<H3><A NAME="other">Building Lua on other systems</A></H3>
224<P>
225 If you're not using the usual Unix tools, then the instructions for
226 building Lua depend on the compiler you use. You'll need to create
227 projects (or whatever your compiler uses) for building the library,
228 the interpreter, and the compiler, as follows:
229
230<DL CLASS="display">
231<DT>
232library:
233<DD>
234lapi.c lcode.c lctype.c ldebug.c ldo.c ldump.c lfunc.c lgc.c llex.c lmem.c lobject.c lopcodes.c lparser.c lstate.c lstring.c ltable.c ltm.c lundump.c lvm.c lzio.c
235lauxlib.c lbaselib.c lcorolib.c ldblib.c liolib.c lmathlib.c loadlib.c loslib.c lstrlib.c ltablib.c lutf8lib.c linit.c
236<DT>
237interpreter:
238<DD>
239 library, lua.c
240<DT>
241compiler:
242<DD>
243 library, luac.c
244</DL>
245
246<P>
247 To use Lua as a library in your own programs, you'll need to know how to
248 create and use libraries with your compiler. Moreover, to dynamically load
249 C libraries for Lua, you'll need to know how to create dynamic libraries
250 and you'll need to make sure that the Lua API functions are accessible to
251 those dynamic libraries — but <EM>don't</EM> link the Lua library
252 into each dynamic library. For Unix, we recommend that the Lua library
253 be linked statically into the host program and its symbols exported for
254 dynamic linking; <TT>src/Makefile</TT> does this for the Lua interpreter.
255 For Windows, we recommend that the Lua library be a DLL.
256 In all cases, the compiler luac should be linked statically.
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.3</A></H2>
263<P>
264Here are the main changes introduced in Lua 5.4.
265The
266<A HREF="contents.html">reference manual</A>
267lists the
268<A HREF="manual.html#8">incompatibilities</A> that had to be introduced.
269
270<H3>Main changes</H3>
271<UL>
272<LI> new generational mode for garbage collection
273<LI> to-be-closed variables
274<LI> const variables
275<LI> userdata can have multiple user values
276<LI> new implementation for math.random
277<LI> warning system
278<LI> debug information about function arguments and returns
279<LI> new semantics for the integer 'for' loop
280<LI> optional 'init' argument to 'string.gmatch'
281<LI> new functions 'lua_resetthread' and 'coroutine.close'
282<LI> string-to-number coercions moved to the string library
283<LI> allocation function allowed to fail when shrinking a memory block
284<LI> new format '%p' in 'string.format'
285<LI> utf8 library accepts codepoints up to 2^31
286</UL>
287
288<H2><A NAME="license">License</A></H2>
289<P>
290<A HREF="http://www.opensource.org/docs/definition.php">
291<IMG SRC="osi-certified-72x60.png" ALIGN="right" ALT="[osi certified]" STYLE="padding-left: 30px ;">
292</A>
293Lua is free software distributed under the terms of the
294<A HREF="http://www.opensource.org/licenses/mit-license.html">MIT license</A>
295reproduced below;
296it may be used for any purpose, including commercial purposes,
297at absolutely no cost without having to ask us.
298
299The only requirement is that if you do use Lua,
300then you should give us credit by including the appropriate copyright notice somewhere in your product or its documentation.
301
302For details, see
303<A HREF="http://www.lua.org/license.html">this</A>.
304
305<BLOCKQUOTE STYLE="padding-bottom: 0em">
306Copyright © 1994–2020 Lua.org, PUC-Rio.
307
308<P>
309Permission is hereby granted, free of charge, to any person obtaining a copy
310of this software and associated documentation files (the "Software"), to deal
311in the Software without restriction, including without limitation the rights
312to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
313copies of the Software, and to permit persons to whom the Software is
314furnished to do so, subject to the following conditions:
315
316<P>
317The above copyright notice and this permission notice shall be included in
318all copies or substantial portions of the Software.
319
320<P>
321THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
322IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
323FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
324AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
325LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
326OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
327THE SOFTWARE.
328</BLOCKQUOTE>
329<P>
330
331<P CLASS="footer">
332Last update:
333Wed Sep 30 09:55:45 UTC 2020
334</P>
335<!--
336Last change: revised for Lua 5.4.1
337-->
338
339</BODY>
340</HTML>
341
