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