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> 32*3068d706SWarner Losh<A HREF="https://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 52*3068d706SWarner Losh<A HREF="https://www.lua.org/authors.html">team</A> 538e3e3a7aSWarner Loshat 54*3068d706SWarner Losh<A HREF="https://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 59*3068d706SWarner Losh<A HREF="https://www.lua.org/uses.html">many products and projects</A> 600495ed39SKyle Evansaround the world. 618e3e3a7aSWarner Losh 628e3e3a7aSWarner Losh<P> 638e3e3a7aSWarner LoshLua's 64*3068d706SWarner Losh<A HREF="https://www.lua.org/">official website</A> 658e3e3a7aSWarner Loshprovides complete information 668e3e3a7aSWarner Loshabout Lua, 678e3e3a7aSWarner Loshincluding 688e3e3a7aSWarner Loshan 69*3068d706SWarner Losh<A HREF="https://www.lua.org/about.html">executive summary</A>, 70*3068d706SWarner Loshtips on 71*3068d706SWarner Losh<A HREF="https://www.lua.org/start.html">getting started</A>, 728e3e3a7aSWarner Loshand 738e3e3a7aSWarner Loshupdated 74*3068d706SWarner Losh<A HREF="https://www.lua.org/docs.html">documentation</A>, 758e3e3a7aSWarner Loshespecially the 76*3068d706SWarner Losh<A HREF="https://www.lua.org/manual/5.4/">reference manual</A>, 778e3e3a7aSWarner Loshwhich may differ slightly from the 788e3e3a7aSWarner Losh<A HREF="contents.html">local copy</A> 798e3e3a7aSWarner Loshdistributed in this package. 808e3e3a7aSWarner Losh 818e3e3a7aSWarner Losh<H2><A NAME="install">Installing Lua</A></H2> 828e3e3a7aSWarner Losh<P> 838e3e3a7aSWarner LoshLua is distributed in 84*3068d706SWarner Losh<A HREF="https://www.lua.org/ftp/">source</A> 858e3e3a7aSWarner Loshform. 868e3e3a7aSWarner LoshYou need to build it before using it. 878e3e3a7aSWarner LoshBuilding Lua should be straightforward 888e3e3a7aSWarner Loshbecause 898e3e3a7aSWarner LoshLua is implemented in pure ANSI C and compiles unmodified in all known 908e3e3a7aSWarner Loshplatforms that have an ANSI C compiler. 918e3e3a7aSWarner LoshLua also compiles unmodified as C++. 920495ed39SKyle EvansThe instructions given below for building Lua are for Unix-like platforms, 93*3068d706SWarner Loshsuch as Linux and macOS. 948e3e3a7aSWarner LoshSee also 958e3e3a7aSWarner Losh<A HREF="#other">instructions for other systems</A> 968e3e3a7aSWarner Loshand 978e3e3a7aSWarner Losh<A HREF="#customization">customization options</A>. 988e3e3a7aSWarner Losh 998e3e3a7aSWarner Losh<P> 1008e3e3a7aSWarner LoshIf you don't have the time or the inclination to compile Lua yourself, 1018e3e3a7aSWarner Loshget a binary from 102*3068d706SWarner Losh<A HREF="https://luabinaries.sourceforge.net">LuaBinaries</A>. 1038e3e3a7aSWarner Losh 1048e3e3a7aSWarner Losh<H3>Building Lua</H3> 1058e3e3a7aSWarner Losh<P> 1060495ed39SKyle EvansIn most common Unix-like platforms, simply do "<KBD>make</KBD>". 1078e3e3a7aSWarner LoshHere are the details. 1088e3e3a7aSWarner Losh 1098e3e3a7aSWarner Losh<OL> 1108e3e3a7aSWarner Losh<LI> 1118e3e3a7aSWarner LoshOpen a terminal window and move to 112*3068d706SWarner Loshthe top-level directory, which is named <TT>lua-5.4.8</TT>. 1138e3e3a7aSWarner LoshThe <TT>Makefile</TT> there controls both the build process and the installation process. 1148e3e3a7aSWarner Losh<P> 1158e3e3a7aSWarner Losh<LI> 1160495ed39SKyle Evans Do "<KBD>make</KBD>". The <TT>Makefile</TT> will guess your platform and build Lua for it. 1170495ed39SKyle Evans<P> 1180495ed39SKyle Evans<LI> 1190495ed39SKyle Evans If the guess failed, do "<KBD>make help</KBD>" and see if your platform is listed. 1208e3e3a7aSWarner Losh The platforms currently supported are: 1218e3e3a7aSWarner Losh<P> 1228e3e3a7aSWarner Losh<P CLASS="display"> 123a9490b81SWarner Losh guess aix bsd c89 freebsd generic ios linux linux-readline macosx mingw posix solaris 1248e3e3a7aSWarner Losh</P> 1258e3e3a7aSWarner Losh<P> 1268e3e3a7aSWarner Losh If your platform is listed, just do "<KBD>make xxx</KBD>", where xxx 1278e3e3a7aSWarner Losh is your platform name. 1288e3e3a7aSWarner Losh<P> 1298e3e3a7aSWarner Losh If your platform is not listed, try the closest one or posix, generic, 1308e3e3a7aSWarner Losh c89, in this order. 1318e3e3a7aSWarner Losh<P> 1328e3e3a7aSWarner Losh<LI> 1338e3e3a7aSWarner LoshThe compilation takes only a few moments 1348e3e3a7aSWarner Loshand produces three files in the <TT>src</TT> directory: 1358e3e3a7aSWarner Loshlua (the interpreter), 1368e3e3a7aSWarner Loshluac (the compiler), 1378e3e3a7aSWarner Loshand liblua.a (the library). 1388e3e3a7aSWarner Losh<P> 1398e3e3a7aSWarner Losh<LI> 1408e3e3a7aSWarner Losh To check that Lua has been built correctly, do "<KBD>make test</KBD>" 1418e3e3a7aSWarner Losh after building Lua. This will run the interpreter and print its version. 1428e3e3a7aSWarner Losh</OL> 1438e3e3a7aSWarner Losh<P> 1440495ed39SKyle EvansIf you're running Linux, try "<KBD>make linux-readline</KBD>" to build the interactive Lua interpreter with handy line-editing and history capabilities. 1450495ed39SKyle EvansIf you get compilation errors, 1468e3e3a7aSWarner Loshmake sure you have installed the <TT>readline</TT> development package 1478e3e3a7aSWarner Losh(which is probably named <TT>libreadline-dev</TT> or <TT>readline-devel</TT>). 1488e3e3a7aSWarner LoshIf you get link errors after that, 1490495ed39SKyle Evansthen try "<KBD>make linux-readline MYLIBS=-ltermcap</KBD>". 1508e3e3a7aSWarner Losh 1518e3e3a7aSWarner Losh<H3>Installing Lua</H3> 1528e3e3a7aSWarner Losh<P> 1538e3e3a7aSWarner Losh Once you have built Lua, you may want to install it in an official 1548e3e3a7aSWarner Losh place in your system. In this case, do "<KBD>make install</KBD>". The official 1558e3e3a7aSWarner Losh place and the way to install files are defined in the <TT>Makefile</TT>. You'll 1560495ed39SKyle Evans probably need the right permissions to install files, and so may need to do "<KBD>sudo make install</KBD>". 1578e3e3a7aSWarner Losh 1588e3e3a7aSWarner Losh<P> 1590495ed39SKyle Evans To build and install Lua in one step, do "<KBD>make all install</KBD>", 1600495ed39SKyle Evans or "<KBD>make xxx install</KBD>", 1618e3e3a7aSWarner Losh where xxx is your platform name. 1628e3e3a7aSWarner Losh 1638e3e3a7aSWarner Losh<P> 1640495ed39SKyle Evans To install Lua locally after building it, do "<KBD>make local</KBD>". 1658e3e3a7aSWarner Losh This will create a directory <TT>install</TT> with subdirectories 1668e3e3a7aSWarner Losh <TT>bin</TT>, <TT>include</TT>, <TT>lib</TT>, <TT>man</TT>, <TT>share</TT>, 1678e3e3a7aSWarner Losh and install Lua as listed below. 1688e3e3a7aSWarner Losh 1698e3e3a7aSWarner Losh To install Lua locally, but in some other directory, do 1708e3e3a7aSWarner Losh "<KBD>make install INSTALL_TOP=xxx</KBD>", where xxx is your chosen directory. 1718e3e3a7aSWarner Losh The installation starts in the <TT>src</TT> and <TT>doc</TT> directories, 1728e3e3a7aSWarner Losh so take care if <TT>INSTALL_TOP</TT> is not an absolute path. 1738e3e3a7aSWarner Losh 1748e3e3a7aSWarner Losh<DL CLASS="display"> 1758e3e3a7aSWarner Losh<DT> 1768e3e3a7aSWarner Losh bin: 1778e3e3a7aSWarner Losh<DD> 1788e3e3a7aSWarner Losh lua luac 1798e3e3a7aSWarner Losh<DT> 1808e3e3a7aSWarner Losh include: 1818e3e3a7aSWarner Losh<DD> 1828e3e3a7aSWarner Losh lua.h luaconf.h lualib.h lauxlib.h lua.hpp 1838e3e3a7aSWarner Losh<DT> 1848e3e3a7aSWarner Losh lib: 1858e3e3a7aSWarner Losh<DD> 1868e3e3a7aSWarner Losh liblua.a 1878e3e3a7aSWarner Losh<DT> 1888e3e3a7aSWarner Losh man/man1: 1898e3e3a7aSWarner Losh<DD> 1908e3e3a7aSWarner Losh lua.1 luac.1 1918e3e3a7aSWarner Losh</DL> 1928e3e3a7aSWarner Losh 1938e3e3a7aSWarner Losh<P> 1948e3e3a7aSWarner Losh These are the only directories you need for development. 1958e3e3a7aSWarner Losh If you only want to run Lua programs, 1968e3e3a7aSWarner Losh you only need the files in <TT>bin</TT> and <TT>man</TT>. 1978e3e3a7aSWarner Losh The files in <TT>include</TT> and <TT>lib</TT> are needed for 1988e3e3a7aSWarner Losh embedding Lua in C or C++ programs. 1998e3e3a7aSWarner Losh 2008e3e3a7aSWarner Losh<H3><A NAME="customization">Customization</A></H3> 2018e3e3a7aSWarner Losh<P> 2028e3e3a7aSWarner Losh Three kinds of things can be customized by editing a file: 2038e3e3a7aSWarner Losh<UL> 2048e3e3a7aSWarner Losh <LI> Where and how to install Lua — edit <TT>Makefile</TT>. 2058e3e3a7aSWarner Losh <LI> How to build Lua — edit <TT>src/Makefile</TT>. 2068e3e3a7aSWarner Losh <LI> Lua features — edit <TT>src/luaconf.h</TT>. 2078e3e3a7aSWarner Losh</UL> 2088e3e3a7aSWarner Losh 2098e3e3a7aSWarner Losh<P> 2108e3e3a7aSWarner Losh You don't actually need to edit the Makefiles because you may set the 2118e3e3a7aSWarner Losh relevant variables in the command line when invoking make. 2128e3e3a7aSWarner Losh Nevertheless, it's probably best to edit and save the Makefiles to 2138e3e3a7aSWarner Losh record the changes you've made. 2148e3e3a7aSWarner Losh 2158e3e3a7aSWarner Losh<P> 216*3068d706SWarner Losh On the other hand, if you need to customize some Lua features, 217*3068d706SWarner Losh edit <TT>src/luaconf.h</TT> before building and installing Lua. 2188e3e3a7aSWarner Losh The edited file will be the one installed, and 2198e3e3a7aSWarner Losh it will be used by any Lua clients that you build, to ensure consistency. 2208e3e3a7aSWarner Losh Further customization is available to experts by editing the Lua sources. 2218e3e3a7aSWarner Losh 2228e3e3a7aSWarner Losh<H3><A NAME="other">Building Lua on other systems</A></H3> 2238e3e3a7aSWarner Losh<P> 2248e3e3a7aSWarner Losh If you're not using the usual Unix tools, then the instructions for 2258e3e3a7aSWarner Losh building Lua depend on the compiler you use. You'll need to create 2268e3e3a7aSWarner Losh projects (or whatever your compiler uses) for building the library, 2278e3e3a7aSWarner Losh the interpreter, and the compiler, as follows: 2288e3e3a7aSWarner Losh 2298e3e3a7aSWarner Losh<DL CLASS="display"> 2308e3e3a7aSWarner Losh<DT> 2318e3e3a7aSWarner Loshlibrary: 2328e3e3a7aSWarner Losh<DD> 2330495ed39SKyle 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 2340495ed39SKyle Evanslauxlib.c lbaselib.c lcorolib.c ldblib.c liolib.c lmathlib.c loadlib.c loslib.c lstrlib.c ltablib.c lutf8lib.c linit.c 2358e3e3a7aSWarner Losh<DT> 2368e3e3a7aSWarner Loshinterpreter: 2378e3e3a7aSWarner Losh<DD> 2388e3e3a7aSWarner Losh library, lua.c 2398e3e3a7aSWarner Losh<DT> 2408e3e3a7aSWarner Loshcompiler: 2418e3e3a7aSWarner Losh<DD> 2428e3e3a7aSWarner Losh library, luac.c 2438e3e3a7aSWarner Losh</DL> 2448e3e3a7aSWarner Losh 2458e3e3a7aSWarner Losh<P> 246*3068d706SWarner Losh To use Lua as a library in your own programs, you need to know how to 2478e3e3a7aSWarner Losh create and use libraries with your compiler. Moreover, to dynamically load 2480495ed39SKyle Evans C libraries for Lua, you'll need to know how to create dynamic libraries 2498e3e3a7aSWarner Losh and you'll need to make sure that the Lua API functions are accessible to 2508e3e3a7aSWarner Losh those dynamic libraries — but <EM>don't</EM> link the Lua library 2518e3e3a7aSWarner Losh into each dynamic library. For Unix, we recommend that the Lua library 2528e3e3a7aSWarner Losh be linked statically into the host program and its symbols exported for 2538e3e3a7aSWarner Losh dynamic linking; <TT>src/Makefile</TT> does this for the Lua interpreter. 2548e3e3a7aSWarner Losh For Windows, we recommend that the Lua library be a DLL. 2558e3e3a7aSWarner Losh In all cases, the compiler luac should be linked statically. 2568e3e3a7aSWarner Losh 2578e3e3a7aSWarner Losh<P> 2588e3e3a7aSWarner Losh As mentioned above, you may edit <TT>src/luaconf.h</TT> to customize 2598e3e3a7aSWarner Losh some features before building Lua. 2608e3e3a7aSWarner Losh 2610495ed39SKyle Evans<H2><A NAME="changes">Changes since Lua 5.3</A></H2> 2628e3e3a7aSWarner Losh<P> 2630495ed39SKyle EvansHere are the main changes introduced in Lua 5.4. 2648e3e3a7aSWarner LoshThe 2658e3e3a7aSWarner Losh<A HREF="contents.html">reference manual</A> 2668e3e3a7aSWarner Loshlists the 2678e3e3a7aSWarner Losh<A HREF="manual.html#8">incompatibilities</A> that had to be introduced. 2688e3e3a7aSWarner Losh 2698e3e3a7aSWarner Losh<H3>Main changes</H3> 2708e3e3a7aSWarner Losh<UL> 2710495ed39SKyle Evans<LI> new generational mode for garbage collection 2720495ed39SKyle Evans<LI> to-be-closed variables 2730495ed39SKyle Evans<LI> const variables 2740495ed39SKyle Evans<LI> userdata can have multiple user values 2750495ed39SKyle Evans<LI> new implementation for math.random 2760495ed39SKyle Evans<LI> warning system 2770495ed39SKyle Evans<LI> debug information about function arguments and returns 2780495ed39SKyle Evans<LI> new semantics for the integer 'for' loop 2790495ed39SKyle Evans<LI> optional 'init' argument to 'string.gmatch' 2800495ed39SKyle Evans<LI> new functions 'lua_resetthread' and 'coroutine.close' 2810495ed39SKyle Evans<LI> string-to-number coercions moved to the string library 2820495ed39SKyle Evans<LI> allocation function allowed to fail when shrinking a memory block 2830495ed39SKyle Evans<LI> new format '%p' in 'string.format' 2840495ed39SKyle Evans<LI> utf8 library accepts codepoints up to 2^31 2858e3e3a7aSWarner Losh</UL> 2868e3e3a7aSWarner Losh 2878e3e3a7aSWarner Losh<H2><A NAME="license">License</A></H2> 2888e3e3a7aSWarner Losh<P> 289*3068d706SWarner Losh<A HREF="https://opensource.org/osd"> 290*3068d706SWarner Losh<IMG SRC="OSIApproved_100X125.png" ALIGN="right" ALT="[Open Source Initiative Approved License]" STYLE="padding-left: 1em" WIDTH=50> 2918e3e3a7aSWarner Losh</A> 2928e3e3a7aSWarner LoshLua is free software distributed under the terms of the 293*3068d706SWarner Losh<A HREF="https://opensource.org/license/mit">MIT license</A> 2948e3e3a7aSWarner Loshreproduced below; 2958e3e3a7aSWarner Loshit may be used for any purpose, including commercial purposes, 2968e3e3a7aSWarner Loshat absolutely no cost without having to ask us. 2978e3e3a7aSWarner Losh 2988e3e3a7aSWarner LoshThe only requirement is that if you do use Lua, 2998e3e3a7aSWarner Loshthen you should give us credit by including the appropriate copyright notice somewhere in your product or its documentation. 3008e3e3a7aSWarner Losh 301*3068d706SWarner LoshFor details, see the 302*3068d706SWarner Losh<A HREF="https://www.lua.org/license.html">license page</A>. 3038e3e3a7aSWarner Losh 3048e3e3a7aSWarner Losh<BLOCKQUOTE STYLE="padding-bottom: 0em"> 305*3068d706SWarner LoshCopyright © 1994–2025 Lua.org, PUC-Rio. 3068e3e3a7aSWarner Losh 3078e3e3a7aSWarner Losh<P> 3088e3e3a7aSWarner LoshPermission is hereby granted, free of charge, to any person obtaining a copy 3098e3e3a7aSWarner Loshof this software and associated documentation files (the "Software"), to deal 3108e3e3a7aSWarner Loshin the Software without restriction, including without limitation the rights 3118e3e3a7aSWarner Loshto use, copy, modify, merge, publish, distribute, sublicense, and/or sell 3128e3e3a7aSWarner Loshcopies of the Software, and to permit persons to whom the Software is 3138e3e3a7aSWarner Loshfurnished to do so, subject to the following conditions: 3148e3e3a7aSWarner Losh 3158e3e3a7aSWarner Losh<P> 3168e3e3a7aSWarner LoshThe above copyright notice and this permission notice shall be included in 3178e3e3a7aSWarner Loshall copies or substantial portions of the Software. 3188e3e3a7aSWarner Losh 3198e3e3a7aSWarner Losh<P> 3208e3e3a7aSWarner LoshTHE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 3218e3e3a7aSWarner LoshIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 3228e3e3a7aSWarner LoshFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 3238e3e3a7aSWarner LoshAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 3248e3e3a7aSWarner LoshLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 3258e3e3a7aSWarner LoshOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 3268e3e3a7aSWarner LoshTHE SOFTWARE. 3278e3e3a7aSWarner Losh</BLOCKQUOTE> 3288e3e3a7aSWarner Losh<P> 3298e3e3a7aSWarner Losh 3308e3e3a7aSWarner Losh<P CLASS="footer"> 3318e3e3a7aSWarner LoshLast update: 332*3068d706SWarner LoshWed May 21 21:12:01 UTC 2025 3338e3e3a7aSWarner Losh</P> 3348e3e3a7aSWarner Losh<!-- 335*3068d706SWarner LoshLast change: revised for Lua 5.4.8 3368e3e3a7aSWarner Losh--> 3378e3e3a7aSWarner Losh 3388e3e3a7aSWarner Losh</BODY> 3398e3e3a7aSWarner Losh</HTML> 340
