Debian Codegraph @

vendor/lua/doc/readme.html

raw
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">
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 <H1>
32 <A HREF="http://www.lua.org/"><IMG SRC="logo.gif" ALT="Lua"></A>
33 Welcome to Lua 5.4
34 </H1>
35
36 <DIV CLASS="menubar">
37 <A HREF="#about">about</A>
38 &middot;
39 <A HREF="#install">installation</A>
40 &middot;
41 <A HREF="#changes">changes</A>
42 &middot;
43 <A HREF="#license">license</A>
44 &middot;
45 <A HREF="contents.html">reference manual</A>
46 </DIV>
47
48 <H2><A NAME="about">About Lua</A></H2>
49 <P>
50 Lua is a powerful, efficient, 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
59 <A HREF="http://www.lua.org/uses.html">many products and projects</A>
60 around the world.
61
62 <P>
63 Lua's
64 <A HREF="http://www.lua.org/">official web site</A>
65 provides complete information
66 about Lua,
67 including
68 an
69 <A HREF="http://www.lua.org/about.html">executive summary</A>
70 and
71 updated
72 <A HREF="http://www.lua.org/docs.html">documentation</A>,
73 especially the
74 <A HREF="http://www.lua.org/manual/5.4/">reference manual</A>,
75 which may differ slightly from the
76 <A HREF="contents.html">local copy</A>
77 distributed in this package.
78
79 <H2><A NAME="install">Installing Lua</A></H2>
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 such as Linux and Mac OS X.
92 See also
93 <A HREF="#other">instructions for other systems</A>
94 and
95 <A HREF="#customization">customization options</A>.
96
97 <P>
98 If you don't have the time or the inclination to compile Lua yourself,
99 get a binary from
100 <A HREF="http://lua-users.org/wiki/LuaBinaries">LuaBinaries</A>.
101 Try also
102 <A HREF="http://luadist.org/">LuaDist</A>,
103 a multi-platform distribution of Lua that includes batteries.
104
105 <H3>Building Lua</H3>
106 <P>
107 In most common Unix-like platforms, simply do "<KBD>make</KBD>".
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.4.3</TT>.
114 The <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>
134 The compilation takes only a few moments
135 and produces three files in the <TT>src</TT> directory:
136 lua (the interpreter),
137 luac (the compiler),
138 and 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>
145 If you're running Linux, try "<KBD>make linux-readline</KBD>" to build the interactive Lua interpreter with handy line-editing and history capabilities.
146 If you get compilation errors,
147 make sure you have installed the <TT>readline</TT> development package
148 (which is probably named <TT>libreadline-dev</TT> or <TT>readline-devel</TT>).
149 If you get link errors after that,
150 then 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 &mdash; edit <TT>Makefile</TT>.
206 <LI> How to build Lua &mdash; edit <TT>src/Makefile</TT>.
207 <LI> Lua features &mdash; 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>
232 library:
233 <DD>
234 lapi.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
235 lauxlib.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>
237 interpreter:
238 <DD>
239 library, lua.c
240 <DT>
241 compiler:
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 &mdash; 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>
264 Here are the main changes introduced in Lua 5.4.
265 The
266 <A HREF="contents.html">reference manual</A>
267 lists 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>
293 Lua is free software distributed under the terms of the
294 <A HREF="http://www.opensource.org/licenses/mit-license.html">MIT license</A>
295 reproduced below;
296 it may be used for any purpose, including commercial purposes,
297 at absolutely no cost without having to ask us.
298
299 The only requirement is that if you do use Lua,
300 then you should give us credit by including the appropriate copyright notice somewhere in your product or its documentation.
301
302 For details, see
303 <A HREF="http://www.lua.org/license.html">this</A>.
304
305 <BLOCKQUOTE STYLE="padding-bottom: 0em">
306 Copyright &copy; 1994&ndash;2021 Lua.org, PUC-Rio.
307
308 <P>
309 Permission is hereby granted, free of charge, to any person obtaining a copy
310 of this software and associated documentation files (the "Software"), to deal
311 in the Software without restriction, including without limitation the rights
312 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
313 copies of the Software, and to permit persons to whom the Software is
314 furnished to do so, subject to the following conditions:
315
316 <P>
317 The above copyright notice and this permission notice shall be included in
318 all copies or substantial portions of the Software.
319
320 <P>
321 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
322 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
323 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
324 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
325 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
326 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
327 THE SOFTWARE.
328 </BLOCKQUOTE>
329 <P>
330
331 <P CLASS="footer">
332 Last update:
333 Wed Mar 3 10:16:26 UTC 2021
334 </P>
335 <!--
336 Last change: revised for Lua 5.4.3
337 -->
338
339 </BODY>
340 </HTML>