diff options
Diffstat (limited to 'doc/readme.html')
| -rw-r--r-- | doc/readme.html | 341 |
1 files changed, 327 insertions, 14 deletions
diff --git a/doc/readme.html b/doc/readme.html index 38be6dbb..7640d3af 100644 --- a/doc/readme.html +++ b/doc/readme.html @@ -1,7 +1,27 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <HTML> <HEAD> -<TITLE>Lua documentation</TITLE> +<TITLE>Lua 5.2 readme</TITLE> <LINK REL="stylesheet" TYPE="text/css" HREF="lua.css"> +<META HTTP-EQUIV="content-type" CONTENT="text/html; charset=iso-8859-1"> +<STYLE TYPE="text/css"> +blockquote, .display { + color: black ; + padding: 8px ; + border: solid #a0a0a0 2px ; + background-color: #EFEFFF ; + margin-left: 0px ; +} + +.review { + color: red ; +} + +.external { + padding-right: 15px; + background: transparent url(external.png) no-repeat center right; +} +</STYLE> </HEAD> <BODY> @@ -9,31 +29,324 @@ <HR> <H1> <A HREF="http://www.lua.org/"><IMG SRC="logo.gif" ALT="Lua" BORDER=0></A> -Documentation +Welcome to Lua 5.2 </H1> -This is the documentation included in the source distribution of Lua 5.1.4. +<A HREF="#about">about</A> +· +<A HREF="#install">installation</A> +· +<A HREF="#changes">changes</A> +· +<A HREF="#license">license</A> +· +<A HREF="contents.html">reference manual</A> +<HR> +<P> -<UL> -<LI><A HREF="contents.html">Reference manual</A> -<LI><A HREF="lua.html">lua man page</A> -<LI><A HREF="luac.html">luac man page</A> -<LI><A HREF="../README">lua/README</A> -<LI><A HREF="../etc/README">lua/etc/README</A> -<LI><A HREF="../test/README">lua/test/README</A> -</UL> +<P> +<IMG SRC="alert.png" ALIGN="absbottom"> +<EM>This is a work version of Lua 5.2. +All details may change in the final version.</EM> + +<H2><A NAME="about">About Lua</A></H2> + +Lua is a powerful, fast, lightweight, embeddable scripting language +developed by a +<A HREF="http://www.lua.org/authors.html">team</A> +at +<A HREF="http://www.puc-rio.br/">PUC-Rio</A>, +the Pontifical Catholic University of Rio de Janeiro in Brazil. +Lua is +<A HREF="#license">free software</A> +used in many products and projects around the world. +<P> Lua's <A HREF="http://www.lua.org/">official web site</A> -contains updated documentation, +provides complete information +about Lua, +including +an +<A HREF="http://www.lua.org/about.html">executive summary</A> +and +updated +<A HREF="http://www.lua.org/docs.html">documentation</A>, especially the -<A HREF="http://www.lua.org/manual/5.1/">reference manual</A>. +<A HREF="http://www.lua.org/manual/5.2/">reference manual</A>, +which may differ slightly from the +<A HREF="contents.html">local copy</A> +distributed in this package. +<P> + +<H2><A NAME="install">Installing Lua</A></H2> +<DIV CLASS="review">how much detail?</DIV><P> + +Lua is distributed in source form. +You need to build it before using it. +This should be straightforward +because +Lua is implemented in pure ANSI C, and compiles unmodified in all known +platforms that have an ANSI C compiler. +Lua also compiles unmodified as C++. +<P> + +The instructions below are for Unix-like platforms. +There are also +<A HREF="#other">instructions for other systems</A>. +See below for +<A HREF="#customization">customization options</A>. +<P> + +<H3>Building Lua</H3> + +In most Unix-like platforms, simply do "make" with a suitable target. +Here are the details. +<P> + +<OL> +<LI> +Open a terminal window and move to +the top-level directory, which is named lua-5.2. +The Makefile there controls both the build process and the installation process. +<P> +<LI> + Do "make" and see if your platform is listed. + The platforms currently supported are: +<BLOCKQUOTE> + aix ansi bsd freebsd generic linux macosx mingw posix solaris +</BLOCKQUOTE> +<P> + If your platform is listed, just do "make xxx", where xxx + is your platform name. +<P> + If your platform is not listed, try the closest one or posix, generic, + ansi, in this order. +<P> +<LI> +The compilation takes only a few moments +and produces three files in the src directory: +lua (the interpreter), +luac (the compiler), +and liblua.a (the library). +<P> +<LI> + If you want to check that Lua has been built correctly, do "make test" + after building Lua. This will run the interpreter on a "hello world" + Lua program from the test directory. + You may want to try other example programs in that directory. +</OL> +<P> + +<H3>Installing Lua</H3> + Once you have built Lua, you may want to install it in an official + place in your system. In this case, do "make install". The official + place and the way to install files are defined in Makefile. You'll + probably need the right permissions to install files. +<P> + + If you want to build and install Lua in one step, do <SPAN CLASS="display">"make xxx install"</SPAN>, + where xxx is your platform name. +<P> + + If you want to install Lua locally, then do "make local". This will + create directories bin, include, lib, man, and install Lua there as + follows: + <SPAN CLASS="review">review!</SPAN> +<P> + +<DL CLASS="display"> +<DT> + bin: +<DD> + lua luac +<DT> + include: +<DD> + lua.h luaconf.h lualib.h lauxlib.h lua.hpp +<DT> + lib: +<DD> + liblua.a +<DT> + man/man1: +<DD> + lua.1 luac.1 +</DL> + + These are the only directories you need for development. +<P> + + There are man pages for + <A HREF="lua.html">lua</A> and + <A HREF="luac.html">luac</A>, in both nroff and html, and a + <A HREF="contents.html">reference manual</A> in html in doc, some sample code in test, and some + useful stuff in etc. You don't need these directories for development. +<P> + + If you want to install Lua locally, but in some other directory, do + "make install INSTALL_TOP=xxx", where xxx is your chosen directory. +<P> + +<H3><A NAME="customization">Customization</A></H3> + Three kinds of things can be customized by editing a file: +<UL> + <LI> Where and how to install Lua – edit Makefile. + <LI> How to build Lua – edit src/Makefile. + <LI> Lua features – edit src/luaconf.h. +</UL> +<P> + + You don't actually need to edit the Makefiles because you may set the + relevant variables in the command line when invoking make. +<P> + + On the other hand, if you need to customize some Lua features, you'll need + to edit src/luaconf.h before building and installing Lua. + The edited file will be the one installed, and + it will be used by any Lua clients that you build, to ensure consistency. +<P> + + We strongly recommend that you enable dynamic loading. This is done + automatically for all platforms listed above that have this feature + and also for Windows. +<P> + +<H3><A NAME="other">Building Lua on other systems</A></H3> + + If you're not using the usual Unix tools, then the instructions for + building Lua depend on the compiler you use. You'll need to create + projects (or whatever your compiler uses) for building the library, + the interpreter, and the compiler, as follows: +<P> +<DL CLASS="display"> +<DT> +library: +<DD> + 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 + lauxlib.c lbaselib.c ldblib.c liolib.c lmathlib.c loslib.c + ltablib.c lstrlib.c loadlib.c linit.c +<DT> +interpreter: +<DD> + library, lua.c +<DT> +compiler: +<DD> + library, luac.c print.c +</DL> + + If you use Visual Studio .NET, you can use etc/luavs.bat in its + "Command Prompt". +<P> + + If all you want is to build the Lua interpreter, you may put all .c files + in a single project, except for luac.c and print.c. Or just use etc/all.c. +<P> + + To use Lua as a library in your own programs you'll need to know how to + create and use libraries with your compiler. Moreover, to dynamically load + C libraries for Lua you'll need to know how to create dynamic libraries + and you'll need to make sure that the Lua API functions are accessible to + those dynamic libraries — but you do <EM>not</EM> want to link the Lua library + into each dynamic library. For Unix, we recommend that the Lua library + be linked statically into the host program and its symbols exported for + dynamic linking; src/Makefile does this for the Lua interpreter. + For Windows, we recommend that the Lua library be DLL. +<P> + + As mentioned above, you may edit src/luaconf.h to customize + some features before building Lua. +<P> + +<H2><A NAME="changes">Changes since Lua 5.1</A></H2> +<DIV CLASS="review">incomplete!</DIV><P> + +Here are the main changes in Lua since its last release. +The +<A HREF="contents.html">reference manual</A> +lists the +<A HREF="manual.html#7">incompatibilities</A> that had to be introduced. +<P> + +<H3>Language</H3> +<UL> +<LI> new lexical environments. +<LI> hex escapes in strings. +<LI> tables and strings honor the <CODE>__len</CODE> metamethod. +</UL> + +<H3>Libraries</H3> +<UL> +<LI> new function <CODE>package.searchpath</CODE>. +<LI> new metamethods <CODE>__pairs</CODE> and <CODE>__ipairs</CODE>. +<LI> arguments for function called through <CODE>xpcall</CODE>. +</UL> + +<H3>Implementation</H3> +<UL> +<LI> emergency garbage collector + (core forces a full collection when allocation fails). +<LI> ephemeron tables + (tables with weak keys only visit value when key is accessible) +<LI> handling of non-string error messages. +<LI> udata with finalizers are kept in a separated list for the GC. +<SPAN CLASS="review">relevant?</SPAN> +</UL> + + +<H2><A NAME="license">License</A></H2> +<A HREF="http://www.opensource.org/docs/definition.php"> +<IMG SRC="osi-certified-72x60.png" ALIGN="right" BORDER="0" ALT="[osi certified]" xSTYLE="padding: 40px ;" hspace="10"> +</A> + +Lua is free software licensed under the terms of the +<A HREF="http://www.opensource.org/licenses/mit-license.html">MIT license</A> +reproduced below, +and +can be used for any purpose, including commercial purposes, +at absolutely no cost without having to ask us. + +The only requirement is that if you do use Lua, +then you should give us credit by including the appropriate copyright notice somewhere in your product or its documentation. + +For details and rationale, see +<A HREF="http://www.lua.org/license.html" class="external">this</A>. +<P> + +<BLOCKQUOTE> +Copyright © 1994-2010 Lua.org, PUC-Rio. +<P> + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: +<P> + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. +<P> + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. +<P> +</BLOCKQUOTE> <P> <HR> <SMALL> Last update: -Tue Aug 12 14:46:07 BRT 2008 +Fri Jan 8 16:41:16 BRST 2010 </SMALL> </BODY> |