18e3e3a7aSWarner Losh<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 28e3e3a7aSWarner Losh<HTML> 38e3e3a7aSWarner Losh<HEAD> 40495ed39SKyle Evans<TITLE>Lua 5.4 readme</TITLE> 58e3e3a7aSWarner Losh<LINK REL="stylesheet" TYPE="text/css" HREF="lua.css"> 68e3e3a7aSWarner Losh<META HTTP-EQUIV="content-type" CONTENT="text/html; charset=iso-8859-1"> 78e3e3a7aSWarner Losh<STYLE TYPE="text/css"> 88e3e3a7aSWarner Loshblockquote, .display { 98e3e3a7aSWarner Losh border: solid #a0a0a0 2px ; 108e3e3a7aSWarner Losh border-radius: 8px ; 118e3e3a7aSWarner Losh padding: 1em ; 128e3e3a7aSWarner Losh margin: 0px ; 138e3e3a7aSWarner Losh} 148e3e3a7aSWarner Losh 158e3e3a7aSWarner Losh.display { 168e3e3a7aSWarner Losh word-spacing: 0.25em ; 178e3e3a7aSWarner Losh} 188e3e3a7aSWarner Losh 198e3e3a7aSWarner Loshdl.display dd { 208e3e3a7aSWarner Losh padding-bottom: 0.2em ; 218e3e3a7aSWarner Losh} 228e3e3a7aSWarner Losh 238e3e3a7aSWarner Loshtt, kbd, code { 248e3e3a7aSWarner Losh font-size: 12pt ; 258e3e3a7aSWarner Losh} 268e3e3a7aSWarner Losh</STYLE> 278e3e3a7aSWarner Losh</HEAD> 288e3e3a7aSWarner Losh 298e3e3a7aSWarner Losh<BODY> 308e3e3a7aSWarner Losh 318e3e3a7aSWarner Losh<H1> 328e3e3a7aSWarner Losh<A HREF="http://www.lua.org/"><IMG SRC="logo.gif" ALT="Lua"></A> 330495ed39SKyle EvansWelcome to Lua 5.4 348e3e3a7aSWarner Losh</H1> 358e3e3a7aSWarner Losh 368e3e3a7aSWarner Losh<DIV CLASS="menubar"> 378e3e3a7aSWarner Losh<A HREF="#about">about</A> 388e3e3a7aSWarner Losh· 398e3e3a7aSWarner Losh<A HREF="#install">installation</A> 408e3e3a7aSWarner Losh· 418e3e3a7aSWarner Losh<A HREF="#changes">changes</A> 428e3e3a7aSWarner Losh· 438e3e3a7aSWarner Losh<A HREF="#license">license</A> 448e3e3a7aSWarner Losh· 458e3e3a7aSWarner Losh<A HREF="contents.html">reference manual</A> 468e3e3a7aSWarner Losh</DIV> 478e3e3a7aSWarner Losh 488e3e3a7aSWarner Losh<H2><A NAME="about">About Lua</A></H2> 498e3e3a7aSWarner Losh<P> 500495ed39SKyle EvansLua is a powerful, efficient, lightweight, embeddable scripting language 518e3e3a7aSWarner Loshdeveloped by a 528e3e3a7aSWarner Losh<A HREF="http://www.lua.org/authors.html">team</A> 538e3e3a7aSWarner Loshat 548e3e3a7aSWarner Losh<A HREF="http://www.puc-rio.br/">PUC-Rio</A>, 558e3e3a7aSWarner Loshthe Pontifical Catholic University of Rio de Janeiro in Brazil. 568e3e3a7aSWarner LoshLua is 578e3e3a7aSWarner Losh<A HREF="#license">free software</A> 580495ed39SKyle Evansused in 590495ed39SKyle Evans<A HREF="http://www.lua.org/uses.html">many products and projects</A> 600495ed39SKyle Evansaround the world. 618e3e3a7aSWarner Losh 628e3e3a7aSWarner Losh<P> 638e3e3a7aSWarner LoshLua's 648e3e3a7aSWarner Losh<A HREF="http://www.lua.org/">official web site</A> 658e3e3a7aSWarner Loshprovides complete information 668e3e3a7aSWarner Loshabout Lua, 678e3e3a7aSWarner Loshincluding 688e3e3a7aSWarner Loshan 698e3e3a7aSWarner Losh<A HREF="http://www.lua.org/about.html">executive summary</A> 708e3e3a7aSWarner Loshand 718e3e3a7aSWarner Loshupdated 728e3e3a7aSWarner Losh<A HREF="http://www.lua.org/docs.html">documentation</A>, 738e3e3a7aSWarner Loshespecially the 740495ed39SKyle Evans<A HREF="http://www.lua.org/manual/5.4/">reference manual</A>, 758e3e3a7aSWarner Loshwhich may differ slightly from the 768e3e3a7aSWarner Losh<A HREF="contents.html">local copy</A> 778e3e3a7aSWarner Loshdistributed in this package. 788e3e3a7aSWarner Losh 798e3e3a7aSWarner Losh<H2><A NAME="install">Installing Lua</A></H2> 808e3e3a7aSWarner Losh<P> 818e3e3a7aSWarner LoshLua is distributed in 828e3e3a7aSWarner Losh<A HREF="http://www.lua.org/ftp/">source</A> 838e3e3a7aSWarner Loshform. 848e3e3a7aSWarner LoshYou need to build it before using it. 858e3e3a7aSWarner LoshBuilding Lua should be straightforward 868e3e3a7aSWarner Loshbecause 878e3e3a7aSWarner LoshLua is implemented in pure ANSI C and compiles unmodified in all known 888e3e3a7aSWarner Loshplatforms that have an ANSI C compiler. 898e3e3a7aSWarner LoshLua also compiles unmodified as C++. 900495ed39SKyle EvansThe instructions given below for building Lua are for Unix-like platforms, 910495ed39SKyle Evanssuch as Linux and Mac OS X. 928e3e3a7aSWarner LoshSee also 938e3e3a7aSWarner Losh<A HREF="#other">instructions for other systems</A> 948e3e3a7aSWarner Loshand 958e3e3a7aSWarner Losh<A HREF="#customization">customization options</A>. 968e3e3a7aSWarner Losh 978e3e3a7aSWarner Losh<P> 988e3e3a7aSWarner LoshIf you don't have the time or the inclination to compile Lua yourself, 998e3e3a7aSWarner Loshget a binary from 1008e3e3a7aSWarner Losh<A HREF="http://lua-users.org/wiki/LuaBinaries">LuaBinaries</A>. 1018e3e3a7aSWarner Losh 1028e3e3a7aSWarner Losh<H3>Building Lua</H3> 1038e3e3a7aSWarner Losh<P> 1040495ed39SKyle EvansIn most common Unix-like platforms, simply do "<KBD>make</KBD>". 1058e3e3a7aSWarner LoshHere are the details. 1068e3e3a7aSWarner Losh 1078e3e3a7aSWarner Losh<OL> 1088e3e3a7aSWarner Losh<LI> 1098e3e3a7aSWarner LoshOpen a terminal window and move to 110*a9490b81SWarner Loshthe top-level directory, which is named <TT>lua-5.4.6</TT>. 1118e3e3a7aSWarner LoshThe <TT>Makefile</TT> there controls both the build process and the installation process. 1128e3e3a7aSWarner Losh<P> 1138e3e3a7aSWarner Losh<LI> 1140495ed39SKyle Evans Do "<KBD>make</KBD>". The <TT>Makefile</TT> will guess your platform and build Lua for it. 1150495ed39SKyle Evans<P> 1160495ed39SKyle Evans<LI> 1170495ed39SKyle Evans If the guess failed, do "<KBD>make help</KBD>" and see if your platform is listed. 1188e3e3a7aSWarner Losh The platforms currently supported are: 1198e3e3a7aSWarner Losh<P> 1208e3e3a7aSWarner Losh<P CLASS="display"> 121*a9490b81SWarner Losh guess aix bsd c89 freebsd generic ios linux linux-readline macosx mingw posix solaris 1228e3e3a7aSWarner Losh</P> 1238e3e3a7aSWarner Losh<P> 1248e3e3a7aSWarner Losh If your platform is listed, just do "<KBD>make xxx</KBD>", where xxx 1258e3e3a7aSWarner Losh is your platform name. 1268e3e3a7aSWarner Losh<P> 1278e3e3a7aSWarner Losh If your platform is not listed, try the closest one or posix, generic, 1288e3e3a7aSWarner Losh c89, in this order. 1298e3e3a7aSWarner Losh<P> 1308e3e3a7aSWarner Losh<LI> 1318e3e3a7aSWarner LoshThe compilation takes only a few moments 1328e3e3a7aSWarner Loshand produces three files in the <TT>src</TT> directory: 1338e3e3a7aSWarner Loshlua (the interpreter), 1348e3e3a7aSWarner Loshluac (the compiler), 1358e3e3a7aSWarner Loshand liblua.a (the library). 1368e3e3a7aSWarner Losh<P> 1378e3e3a7aSWarner Losh<LI> 1388e3e3a7aSWarner Losh To check that Lua has been built correctly, do "<KBD>make test</KBD>" 1398e3e3a7aSWarner Losh after building Lua. This will run the interpreter and print its version. 1408e3e3a7aSWarner Losh</OL> 1418e3e3a7aSWarner Losh<P> 1420495ed39SKyle EvansIf you're running Linux, try "<KBD>make linux-readline</KBD>" to build the interactive Lua interpreter with handy line-editing and history capabilities. 1430495ed39SKyle EvansIf you get compilation errors, 1448e3e3a7aSWarner Loshmake sure you have installed the <TT>readline</TT> development package 1458e3e3a7aSWarner Losh(which is probably named <TT>libreadline-dev</TT> or <TT>readline-devel</TT>). 1468e3e3a7aSWarner LoshIf you get link errors after that, 1470495ed39SKyle Evansthen try "<KBD>make linux-readline MYLIBS=-ltermcap</KBD>". 1488e3e3a7aSWarner Losh 1498e3e3a7aSWarner Losh<H3>Installing Lua</H3> 1508e3e3a7aSWarner Losh<P> 1518e3e3a7aSWarner Losh Once you have built Lua, you may want to install it in an official 1528e3e3a7aSWarner Losh place in your system. In this case, do "<KBD>make install</KBD>". The official 1538e3e3a7aSWarner Losh place and the way to install files are defined in the <TT>Makefile</TT>. You'll 1540495ed39SKyle Evans probably need the right permissions to install files, and so may need to do "<KBD>sudo make install</KBD>". 1558e3e3a7aSWarner Losh 1568e3e3a7aSWarner Losh<P> 1570495ed39SKyle Evans To build and install Lua in one step, do "<KBD>make all install</KBD>", 1580495ed39SKyle Evans or "<KBD>make xxx install</KBD>", 1598e3e3a7aSWarner Losh where xxx is your platform name. 1608e3e3a7aSWarner Losh 1618e3e3a7aSWarner Losh<P> 1620495ed39SKyle Evans To install Lua locally after building it, do "<KBD>make local</KBD>". 1638e3e3a7aSWarner Losh This will create a directory <TT>install</TT> with subdirectories 1648e3e3a7aSWarner Losh <TT>bin</TT>, <TT>include</TT>, <TT>lib</TT>, <TT>man</TT>, <TT>share</TT>, 1658e3e3a7aSWarner Losh and install Lua as listed below. 1668e3e3a7aSWarner Losh 1678e3e3a7aSWarner Losh To install Lua locally, but in some other directory, do 1688e3e3a7aSWarner Losh "<KBD>make install INSTALL_TOP=xxx</KBD>", where xxx is your chosen directory. 1698e3e3a7aSWarner Losh The installation starts in the <TT>src</TT> and <TT>doc</TT> directories, 1708e3e3a7aSWarner Losh so take care if <TT>INSTALL_TOP</TT> is not an absolute path. 1718e3e3a7aSWarner Losh 1728e3e3a7aSWarner Losh<DL CLASS="display"> 1738e3e3a7aSWarner Losh<DT> 1748e3e3a7aSWarner Losh bin: 1758e3e3a7aSWarner Losh<DD> 1768e3e3a7aSWarner Losh lua luac 1778e3e3a7aSWarner Losh<DT> 1788e3e3a7aSWarner Losh include: 1798e3e3a7aSWarner Losh<DD> 1808e3e3a7aSWarner Losh lua.h luaconf.h lualib.h lauxlib.h lua.hpp 1818e3e3a7aSWarner Losh<DT> 1828e3e3a7aSWarner Losh lib: 1838e3e3a7aSWarner Losh<DD> 1848e3e3a7aSWarner Losh liblua.a 1858e3e3a7aSWarner Losh<DT> 1868e3e3a7aSWarner Losh man/man1: 1878e3e3a7aSWarner Losh<DD> 1888e3e3a7aSWarner Losh lua.1 luac.1 1898e3e3a7aSWarner Losh</DL> 1908e3e3a7aSWarner Losh 1918e3e3a7aSWarner Losh<P> 1928e3e3a7aSWarner Losh These are the only directories you need for development. 1938e3e3a7aSWarner Losh If you only want to run Lua programs, 1948e3e3a7aSWarner Losh you only need the files in <TT>bin</TT> and <TT>man</TT>. 1958e3e3a7aSWarner Losh The files in <TT>include</TT> and <TT>lib</TT> are needed for 1968e3e3a7aSWarner Losh embedding Lua in C or C++ programs. 1978e3e3a7aSWarner Losh 1988e3e3a7aSWarner Losh<H3><A NAME="customization">Customization</A></H3> 1998e3e3a7aSWarner Losh<P> 2008e3e3a7aSWarner Losh Three kinds of things can be customized by editing a file: 2018e3e3a7aSWarner Losh<UL> 2028e3e3a7aSWarner Losh <LI> Where and how to install Lua — edit <TT>Makefile</TT>. 2038e3e3a7aSWarner Losh <LI> How to build Lua — edit <TT>src/Makefile</TT>. 2048e3e3a7aSWarner Losh <LI> Lua features — edit <TT>src/luaconf.h</TT>. 2058e3e3a7aSWarner Losh</UL> 2068e3e3a7aSWarner Losh 2078e3e3a7aSWarner Losh<P> 2088e3e3a7aSWarner Losh You don't actually need to edit the Makefiles because you may set the 2098e3e3a7aSWarner Losh relevant variables in the command line when invoking make. 2108e3e3a7aSWarner Losh Nevertheless, it's probably best to edit and save the Makefiles to 2118e3e3a7aSWarner Losh record the changes you've made. 2128e3e3a7aSWarner Losh 2138e3e3a7aSWarner Losh<P> 2148e3e3a7aSWarner Losh On the other hand, if you need to customize some Lua features, you'll need 2158e3e3a7aSWarner Losh to edit <TT>src/luaconf.h</TT> before building and installing Lua. 2168e3e3a7aSWarner Losh The edited file will be the one installed, and 2178e3e3a7aSWarner Losh it will be used by any Lua clients that you build, to ensure consistency. 2188e3e3a7aSWarner Losh Further customization is available to experts by editing the Lua sources. 2198e3e3a7aSWarner Losh 2208e3e3a7aSWarner Losh<H3><A NAME="other">Building Lua on other systems</A></H3> 2218e3e3a7aSWarner Losh<P> 2228e3e3a7aSWarner Losh If you're not using the usual Unix tools, then the instructions for 2238e3e3a7aSWarner Losh building Lua depend on the compiler you use. You'll need to create 2248e3e3a7aSWarner Losh projects (or whatever your compiler uses) for building the library, 2258e3e3a7aSWarner Losh the interpreter, and the compiler, as follows: 2268e3e3a7aSWarner Losh 2278e3e3a7aSWarner Losh<DL CLASS="display"> 2288e3e3a7aSWarner Losh<DT> 2298e3e3a7aSWarner Loshlibrary: 2308e3e3a7aSWarner Losh<DD> 2310495ed39SKyle Evanslapi.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 2320495ed39SKyle Evanslauxlib.c lbaselib.c lcorolib.c ldblib.c liolib.c lmathlib.c loadlib.c loslib.c lstrlib.c ltablib.c lutf8lib.c linit.c 2338e3e3a7aSWarner Losh<DT> 2348e3e3a7aSWarner Loshinterpreter: 2358e3e3a7aSWarner Losh<DD> 2368e3e3a7aSWarner Losh library, lua.c 2378e3e3a7aSWarner Losh<DT> 2388e3e3a7aSWarner Loshcompiler: 2398e3e3a7aSWarner Losh<DD> 2408e3e3a7aSWarner Losh library, luac.c 2418e3e3a7aSWarner Losh</DL> 2428e3e3a7aSWarner Losh 2438e3e3a7aSWarner Losh<P> 2440495ed39SKyle Evans To use Lua as a library in your own programs, you'll need to know how to 2458e3e3a7aSWarner Losh create and use libraries with your compiler. Moreover, to dynamically load 2460495ed39SKyle Evans C libraries for Lua, you'll need to know how to create dynamic libraries 2478e3e3a7aSWarner Losh and you'll need to make sure that the Lua API functions are accessible to 2488e3e3a7aSWarner Losh those dynamic libraries — but <EM>don't</EM> link the Lua library 2498e3e3a7aSWarner Losh into each dynamic library. For Unix, we recommend that the Lua library 2508e3e3a7aSWarner Losh be linked statically into the host program and its symbols exported for 2518e3e3a7aSWarner Losh dynamic linking; <TT>src/Makefile</TT> does this for the Lua interpreter. 2528e3e3a7aSWarner Losh For Windows, we recommend that the Lua library be a DLL. 2538e3e3a7aSWarner Losh In all cases, the compiler luac should be linked statically. 2548e3e3a7aSWarner Losh 2558e3e3a7aSWarner Losh<P> 2568e3e3a7aSWarner Losh As mentioned above, you may edit <TT>src/luaconf.h</TT> to customize 2578e3e3a7aSWarner Losh some features before building Lua. 2588e3e3a7aSWarner Losh 2590495ed39SKyle Evans<H2><A NAME="changes">Changes since Lua 5.3</A></H2> 2608e3e3a7aSWarner Losh<P> 2610495ed39SKyle EvansHere are the main changes introduced in Lua 5.4. 2628e3e3a7aSWarner LoshThe 2638e3e3a7aSWarner Losh<A HREF="contents.html">reference manual</A> 2648e3e3a7aSWarner Loshlists the 2658e3e3a7aSWarner Losh<A HREF="manual.html#8">incompatibilities</A> that had to be introduced. 2668e3e3a7aSWarner Losh 2678e3e3a7aSWarner Losh<H3>Main changes</H3> 2688e3e3a7aSWarner Losh<UL> 2690495ed39SKyle Evans<LI> new generational mode for garbage collection 2700495ed39SKyle Evans<LI> to-be-closed variables 2710495ed39SKyle Evans<LI> const variables 2720495ed39SKyle Evans<LI> userdata can have multiple user values 2730495ed39SKyle Evans<LI> new implementation for math.random 2740495ed39SKyle Evans<LI> warning system 2750495ed39SKyle Evans<LI> debug information about function arguments and returns 2760495ed39SKyle Evans<LI> new semantics for the integer 'for' loop 2770495ed39SKyle Evans<LI> optional 'init' argument to 'string.gmatch' 2780495ed39SKyle Evans<LI> new functions 'lua_resetthread' and 'coroutine.close' 2790495ed39SKyle Evans<LI> string-to-number coercions moved to the string library 2800495ed39SKyle Evans<LI> allocation function allowed to fail when shrinking a memory block 2810495ed39SKyle Evans<LI> new format '%p' in 'string.format' 2820495ed39SKyle Evans<LI> utf8 library accepts codepoints up to 2^31 2838e3e3a7aSWarner Losh</UL> 2848e3e3a7aSWarner Losh 2858e3e3a7aSWarner Losh<H2><A NAME="license">License</A></H2> 2868e3e3a7aSWarner Losh<P> 2878e3e3a7aSWarner Losh<A HREF="http://www.opensource.org/docs/definition.php"> 2888e3e3a7aSWarner Losh<IMG SRC="osi-certified-72x60.png" ALIGN="right" ALT="[osi certified]" STYLE="padding-left: 30px ;"> 2898e3e3a7aSWarner Losh</A> 2908e3e3a7aSWarner LoshLua is free software distributed under the terms of the 2918e3e3a7aSWarner Losh<A HREF="http://www.opensource.org/licenses/mit-license.html">MIT license</A> 2928e3e3a7aSWarner Loshreproduced below; 2938e3e3a7aSWarner Loshit may be used for any purpose, including commercial purposes, 2948e3e3a7aSWarner Loshat absolutely no cost without having to ask us. 2958e3e3a7aSWarner Losh 2968e3e3a7aSWarner LoshThe only requirement is that if you do use Lua, 2978e3e3a7aSWarner Loshthen you should give us credit by including the appropriate copyright notice somewhere in your product or its documentation. 2988e3e3a7aSWarner Losh 2998e3e3a7aSWarner LoshFor details, see 3008e3e3a7aSWarner Losh<A HREF="http://www.lua.org/license.html">this</A>. 3018e3e3a7aSWarner Losh 3028e3e3a7aSWarner Losh<BLOCKQUOTE STYLE="padding-bottom: 0em"> 303*a9490b81SWarner LoshCopyright © 1994–2023 Lua.org, PUC-Rio. 3048e3e3a7aSWarner Losh 3058e3e3a7aSWarner Losh<P> 3068e3e3a7aSWarner LoshPermission is hereby granted, free of charge, to any person obtaining a copy 3078e3e3a7aSWarner Loshof this software and associated documentation files (the "Software"), to deal 3088e3e3a7aSWarner Loshin the Software without restriction, including without limitation the rights 3098e3e3a7aSWarner Loshto use, copy, modify, merge, publish, distribute, sublicense, and/or sell 3108e3e3a7aSWarner Loshcopies of the Software, and to permit persons to whom the Software is 3118e3e3a7aSWarner Loshfurnished to do so, subject to the following conditions: 3128e3e3a7aSWarner Losh 3138e3e3a7aSWarner Losh<P> 3148e3e3a7aSWarner LoshThe above copyright notice and this permission notice shall be included in 3158e3e3a7aSWarner Loshall copies or substantial portions of the Software. 3168e3e3a7aSWarner Losh 3178e3e3a7aSWarner Losh<P> 3188e3e3a7aSWarner LoshTHE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 3198e3e3a7aSWarner LoshIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 3208e3e3a7aSWarner LoshFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 3218e3e3a7aSWarner LoshAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 3228e3e3a7aSWarner LoshLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 3238e3e3a7aSWarner LoshOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 3248e3e3a7aSWarner LoshTHE SOFTWARE. 3258e3e3a7aSWarner Losh</BLOCKQUOTE> 3268e3e3a7aSWarner Losh<P> 3278e3e3a7aSWarner Losh 3288e3e3a7aSWarner Losh<P CLASS="footer"> 3298e3e3a7aSWarner LoshLast update: 330*a9490b81SWarner LoshTue May 2 20:08:55 UTC 2023 3318e3e3a7aSWarner Losh</P> 3328e3e3a7aSWarner Losh<!-- 333*a9490b81SWarner LoshLast change: revised for Lua 5.4.6 3348e3e3a7aSWarner Losh--> 3358e3e3a7aSWarner Losh 3368e3e3a7aSWarner Losh</BODY> 3378e3e3a7aSWarner Losh</HTML> 338
