Update docs for PPC port. Clarify and extend install instructions.

5 files changed, 177 insertions, 65 deletions

diff --git a/doc/faq.html b/doc/faq.html
index 90f37cef..9404f788 100644
--- a/doc/faq.html
+++ b/doc/faq.html
@@ -126,7 +126,7 @@ running inside a C function under the Lua interpreter.</dd>
 <dt>Q: Why doesn't my favorite power-patch for Lua apply against LuaJIT?</dt>
 <dd>Because it's a completely redesigned VM and has very little code
 in common with Lua anymore. Also, if the patch introduces changes to
-the Lua semantics, this would need to be reflected everywhere in the
+the Lua semantics, these would need to be reflected everywhere in the
 VM, from the interpreter up to all stages of the compiler.<br> Please
 use only standard Lua language constructs. For many common needs you
 can use source transformations or use wrapper or proxy functions.
@@ -139,8 +139,8 @@ The compiler will happily optimize away such indirections.</dd>
 machine code. This means the code generator must be ported to each
 architecture. And the fast interpreter is written in assembler and
 must be ported, too. This is quite an undertaking.<br> Currently only
-x86 and x64 CPUs are supported. Other architectures will follow based
-on sufficient user demand and/or sponsoring.</dd>
+x86, x64 and PPC/e500v2 CPUs are supported. Other architectures will follow
+based on sufficient user demand and/or sponsoring.</dd>
 </dl>
 
 <dl>
diff --git a/doc/install.html b/doc/install.html
index 45925e7a..b0c806db 100644
--- a/doc/install.html
+++ b/doc/install.html
@@ -11,16 +11,20 @@
 <style type="text/css">
 table.compat {
   line-height: 1.2;
-  width: 40em;
+  width: 47em;
 }
 tr.compathead td {
   font-weight: bold;
 }
+td {
+  border-left: 1px solid #bfcfff;
+  border-right: 1px solid #bfcfff;
+}
 td.compatos {
-  width: 40%;
+  width: 25%;
 }
 td.compatcc {
-  width: 30%;
+  width: 25%;
   vertical-align: top;
 }
 </style>
@@ -68,35 +72,40 @@ For the impatient (on POSIX systems):
 make &amp;&amp; sudo make install
 </pre>
 <p>
-LuaJIT currently builds out-of-the box on most x86 or x64 systems.
+LuaJIT currently builds out-of-the box on most systems.
 Here's the compatibility matrix for the supported combinations of
 operating system, CPU and compilers:
 </p>
 <table class="compat">
 <tr class="compathead">
-<td class="compatos">Operating system</td>
+<td class="compatos">OS / CPU</td>
 <td class="compatcc">x86 (32 bit)</td>
 <td class="compatcc">x64 (64 bit)</td>
+<td class="compatcc">PPC/e500v2</td>
 </tr>
 <tr class="odd separate">
-<td class="compatos">Linux</td>
+<td class="compatos"><a href="#posix">Linux</a></td>
 <td class="compatcc">GCC 4.x<br>GCC 3.4</td>
 <td class="compatcc">GCC 4.x</td>
+<td class="compatcc">GCC 4.3+</td>
 </tr>
 <tr class="even">
-<td class="compatos">Windows 98/XP/Vista/7</td>
+<td class="compatos"><a href="#windows">Windows<br>98/XP/Vista/7</a></td>
 <td class="compatcc">MSVC (EE)<br>Windows SDK<br>MinGW (GCC)<br>Cygwin (GCC)</td>
 <td class="compatcc">MSVC + SDK v7.0<br>Windows SDK v7.0</td>
+<td class="compatcc">&nbsp;</td>
 </tr>
 <tr class="odd">
-<td class="compatos">OSX 10.3-10.6</td>
+<td class="compatos"><a href="#posix">OSX 10.3-10.6</a></td>
 <td class="compatcc">GCC 4.x<br>GCC 3.4</td>
 <td class="compatcc">GCC 4.x</td>
+<td class="compatcc">&nbsp;</td>
 </tr>
 <tr class="even">
-<td class="compatos">*BSD, other</td>
+<td class="compatos"><a href="#posix">*BSD, other</a></td>
 <td class="compatcc">GCC 4.x<br>GCC 3.4</td>
 <td class="compatcc">(not supported)</td>
+<td class="compatcc">&nbsp;</td>
 </tr>
 </table>
 
@@ -147,10 +156,12 @@ which is probably the default on your system, anyway. Simply run:
 make
 </pre>
 <p>
-This always builds a native x86 or x64 binary, depending on your OS.
+This always builds a native x86, x64 or PPC binary, depending on the host OS
+you're running this command on. Check the section on
+<a href="#cross">cross-compilation</a> for more options.
 </p>
 <p>
-By default modules are only searched under the prefix <tt>/usr/local</tt>.
+By default, modules are only searched under the prefix <tt>/usr/local</tt>.
 You can add an extra prefix to the search paths by appending the
 <tt>PREFIX</tt> option, e.g.:
 </p>
@@ -283,7 +294,7 @@ directory where <tt>luajit.exe</tt> is installed
 (see <tt>src/luaconf.h</tt>).
 </p>
 
-<h2>Cross-compiling LuaJIT</h2>
+<h2 id="cross">Cross-compiling LuaJIT</h2>
 <p>
 The build system has limited support for cross-compilation. For details
 check the comments in <tt>src/Makefile</tt>. Here are some popular examples:
@@ -303,36 +314,130 @@ installing the <tt>mingw32</tt> package and running:
 <pre class="code">
 make HOST_CC="gcc -m32" CROSS=i586-mingw32msvc- TARGET_SYS=Windows
 </pre>
+<p>
+You can cross-compile for a PPC/e500v2 target on an x86 or x64 host system
+using a standard GNU cross-compile toolchain (Binutils, GCC, EGLIBC).
+The <tt>CROSS</tt> prefix may vary depending on the <tt>--target</tt>
+of the toolchain:
+</p>
+<pre class="code">
+make HOST_CC="gcc -m32" CROSS=powerpc-e500v2-linux-gnuspe- TARGET=ppcspe
+</pre>
 
-<h2>Embedding LuaJIT</h2>
+<h2 id="embed">Embedding LuaJIT</h2>
 <p>
 LuaJIT is API-compatible with Lua 5.1. If you've already embedded Lua
 into your application, you probably don't need to do anything to switch
-to LuaJIT, except link with a different library. Additional hints:
+to LuaJIT, except link with a different library:
 </p>
 <ul>
+<li>It's strongly suggested to build LuaJIT separately using the supplied
+build system. Please do <em>not</em> attempt to integrate the individual
+source files into your build tree. You'll most likely get the internal build
+dependencies wrong or mess up the compiler flags. Treat LuaJIT like any
+other external library and link your application with either the dynamic
+or static library, depending on your needs.</li>
+<li>If you want to load C modules compiled for plain Lua
+with <tt>require()</tt>, you need to make sure the public symbols
+(e.g. <tt>lua_pushnumber</tt>) are exported, too:
+<ul><li>On POSIX systems you can either link to the shared library
+or link the static library into your application. In the latter case
+you'll need to export all public symbols from your main executable
+(e.g. <tt>-Wl,-E</tt> on Linux) and add the external dependencies
+(e.g. <tt>-lm -ldl</tt> on Linux).</li>
+<li>Since Windows symbols are bound to a specific DLL name, you need to
+link to the <tt>lua51.dll</tt> created by the LuaJIT build (do not rename
+the DLL). You may link LuaJIT statically on Windows only if you don't
+intend to load Lua/C modules at runtime.
+</li></ul>
+</li>
+<li>
+If you're building a 64 bit application on OSX which links directly or
+indirectly against LuaJIT, you need to link your main executable
+with these flags:
+<pre class="code">
+-pagezero_size 10000 -image_base 100000000
+</pre>
+Also, it's recommended to <tt>rebase</tt> all (self-compiled) shared libraries
+which are loaded at runtime on OSX/x64 (e.g. C extension modules for Lua).
+See: <tt>man rebase</tt>
+</li>
+</ul>
+<p>Additional hints for initializing LuaJIT using the C API functions:</p>
+<ul>
+<li>Here's a
+<a href="http://lua-users.org/wiki/SimpleLuaApiExample"><span class="ext">&raquo;</span>&nbsp;simple example</a>
+for embedding Lua or LuaJIT into your application.</li>
 <li>Make sure you use <tt>luaL_newstate</tt>. Avoid using
 <tt>lua_newstate</tt>, since this uses the (slower) default memory
 allocator from your system (no support for this on x64).</tt></li>
 <li>Make sure you use <tt>luaL_openlibs</tt> and not the old Lua 5.0 style
 of calling <tt>luaopen_base</tt> etc. directly.</li>
-<li>To change which standard libraries to load, copy <tt>src/lib_init.c</tt>
-to your project and modify it accordingly. Make sure the <tt>jit</tt>
-library is loaded or the JIT compiler will not be activated.</li>
-<li>Here's a
-<a href="http://lua-users.org/wiki/SimpleLuaApiExample"><span class="ext">&raquo;</span>&nbsp;simple example</a>.</li>
+<li>To change or extend the list of standard libraries to load, copy
+<tt>src/lib_init.c</tt> to your project and modify it accordingly.
+Make sure the <tt>jit</tt> library is loaded or the JIT compiler
+will not be activated.</li>
+<li>The <tt>bit.*</tt> module for bitwise operations
+is already built-in. There's no need to statically link
+<a href="http://bitop.luajit.org/"><span class="ext">&raquo;</span>&nbsp;Lua BitOp</a> to your application.</li>
 </ul>
+
+<h2 id="distro">Hints for Distribution Maintainers</h2>
+<p>
+The LuaJIT build system has extra provisions for the needs of most
+POSIX-based distributions. If you're a package maintainer for
+a distribution, <em>please</em> make use of these features and
+avoid patching, subverting, autotoolizing or messing up the build system
+in unspeakable ways.
+</p>
+<p>
+There should be absolutely no need to patch <tt>luaconf.h</tt> or any
+of the Makefiles. And please do not hand-pick files for your packages &mdash;
+simply use whatever <tt>make install</tt> creates. There's a reason
+for all of the files <em>and</em> directories it creates.
+</p>
+<p>
+The build system uses GNU make and autodetects most settings based on
+the host you're building it on. This should work fine for native builds,
+even when sandboxed. You may need to pass some of the following flags to
+<em>both</em> the <tt>make</tt> and the <tt>make install</tt> command lines
+for a regular distribution build:
+</p>
+<ul>
+<li><tt>PREFIX</tt> overrides the installation path and should usually
+be set to <tt>/usr</tt>. Setting this also changes the module paths and
+the <tt>-rpath</tt> of the shared library.</li>
+<li><tt>DESTDIR</tt> is an absolute path which allows you to install
+to a shadow tree instead of the root tree of the build system.</li>
+<li>Have a look at the top-level <tt>Makefile</tt> and <tt>src/Makefile</tt>
+for additional variables to tweak. The following variables <em>may</em> be
+overriden, but it's <em>not</em> recommended, except for special needs
+like cross-builds:
+<tt>BUILDMODE, CC, HOST_CC, STATIC_CC, DYNAMIC_CC, CFLAGS, HOST_CFLAGS,
+TARGET_CFLAGS, LDFLAGS, HOST_LDFLAGS, TARGET_LDFLAGS, TARGET_SHLDFLAGS,
+LIBS, HOST_LIBS, TARGET_LIBS, CROSS, HOST_SYS, TARGET_SYS</tt></li>
+</ul>
+<p>
+The build system has a special target for an amalgamated build, i.e.
+<tt>make amalg</tt>. This compiles the LuaJIT core as one huge C file
+and allows GCC to generate faster and shorter code. Alas, this requires
+lots of memory during the build. This may be a problem for some users,
+that's why it's not enabled by default. But it shouldn't be a problem for
+most build farms. It's recommended that binary distributions use this
+target for their LuaJIT builds.
+</p>
 <p>
-64 bit applications on OSX must be linked with these options
-(only the main executable):
+The tl;dr version of the above:
 </p>
 <pre class="code">
--pagezero_size 10000 -image_base 100000000
+make amalg PREFIX=/usr && \
+make install PREFIX=/usr DESTDIR=/tmp/buildroot
 </pre>
 <p>
-It's recommended to <tt>rebase</tt> all (self-compiled) shared libraries
-which are loaded at runtime on OSX/x64 (e.g. C extension modules for Lua).
-See: <tt>man rebase</tt>
+Finally, if you encounter any difficulties, please
+<a href="contact.html">contact me</a> first, instead of releasing a broken
+package onto unsuspecting users. Because they'll usually gonna complain
+to me (the upstream) and not you (the package maintainer), anyway.
 </p>
 <br class="flush">
 </div>
diff --git a/doc/luajit.html b/doc/luajit.html
index 90cd9997..71e6a19f 100644
--- a/doc/luajit.html
+++ b/doc/luajit.html
@@ -65,7 +65,8 @@ standard Lua interpreter and can be deployed as a drop-in replacement.
 <p>
 LuaJIT offers more performance, at the expense of portability. It
 currently runs on all popular operating systems based on
-<b>x86 or x64 CPUs</b> (Linux, Windows, OSX etc.).
+<b>x86</b> or <b>x64 CPUs</b> (Linux, Windows, OSX etc.) or embedded Linux
+systems based on <b>PPC/e500v2 CPUs</b>.
 Other platforms will be supported in the future, based on user demand
 and sponsoring.
 </p>
@@ -76,7 +77,7 @@ LuaJIT has been successfully used as a <b>scripting middleware</b> in
 games, 3D modellers, numerical simulations, trading platforms and many
 other specialty applications. It combines high flexibility with high
 performance and an unmatched <b>low memory footprint</b>: less than
-<b>120K</b> for the VM plus less than <b>80K</b> for the JIT compiler.
+<b>120K</b> for the VM plus less than <b>80K</b> for the JIT compiler (on x86).
 </p>
 <p>
 LuaJIT has been in continuous development since 2005. It's widely
@@ -96,9 +97,13 @@ written in assembler, with a state-of-the-art JIT compiler.
 An innovative <b>trace compiler</b> is integrated with advanced,
 SSA-based optimizations and a highly tuned code generation backend. This
 allows a substantial reduction of the overhead associated with dynamic
-language features. It's destined to break into the
-<a href="http://luajit.org/performance.html"><span class="ext">&raquo;</span>&nbsp;performance</a> range
-traditionally reserved for offline, static language compilers.
+language features.
+</p>
+<p>
+It's destined to break into the <a href="http://luajit.org/performance.html"><span class="ext">&raquo;</span>&nbsp;performance</a>
+range traditionally reserved for offline, static language compilers.
+Have look at these <a href="http://shootout.alioth.debian.org/u32/benchmark.php?test=all&lang=all&d=data&calc=calculate&gpp=on&java=on&luajit=on&v8=on&lua=on&tracemonkey=on&box=1"><span class="ext">&raquo;</span>&nbsp;cross-language benchmarks</a>
+to see how it ranks against the competition.
 </p>
 
 <h2>More ...</h2>
diff --git a/doc/running.html b/doc/running.html
index e3a2a4b0..e337d535 100644
--- a/doc/running.html
+++ b/doc/running.html
@@ -126,7 +126,7 @@ systems.
 </p>
 
 <h3 id="opt_O"><tt>-O[level]</tt><br>
-<tt>-O[+]flag</tt> <tt>-O-flag</tt><br>
+<tt>-O[+]flag</tt>&nbsp;&nbsp;&nbsp;<tt>-O-flag</tt><br>
 <tt>-Oparam=value</tt></h3>
 <p>
 This options allows fine-tuned control of the optimizations used by
diff --git a/doc/status.html b/doc/status.html
index 3da8fe78..a2de90ab 100644
--- a/doc/status.html
+++ b/doc/status.html
@@ -67,30 +67,31 @@ This is a list of the things you should know about the LuaJIT 2.0 beta test:
 </p>
 <ul>
 <li>
-The JIT compiler only generates code for CPUs with support for
-<b>SSE2</b> instructions. I.e. you need at least a P4, Core 2/i5/i7
-or K8/K10 to get the full benefit.<br>
-If you run LuaJIT on older CPUs without SSE2 support, the JIT compiler
-is disabled and the VM falls back to the interpreter.
-Run the command line executable without arguments to show the current status 
-(<tt>JIT: ON</tt> or <tt>JIT: OFF</tt>).
-</li>
-<li>
 Obviously there will be many <b>bugs</b> in a VM which has been
 rewritten from the ground up. Please report your findings together with
-the circumstances needed to reproduce the bug. If possible reduce the
-problem down to a simple test cases.<br>
+the circumstances needed to reproduce the bug. If possible, reduce the
+problem down to a simple test case.<br>
 There is no formal bug tracker at the moment. The best place for
 discussion is the
 <a href="http://www.lua.org/lua-l.html"><span class="ext">&raquo;</span>&nbsp;Lua mailing list</a>. Of course
-you may also send your bug report directly to me, especially when they
-contains lengthy debug output. Please check the
-<a href="contact.html">Contact</a> page for details.
+you may also send your bug reports <a href="contact.html">directly to me</a>,
+especially when they contain lengthy debug output or if you require
+confidentiality.
+</li>
+<li>
+The JIT compiler only generates code for CPUs with support for
+<b>SSE2</b> instructions. I.e. you need at least a P4, Core 2/i3/i5/i7,
+Atom or K8/K10 to get the full benefit.<br>
+If you run LuaJIT on older CPUs without SSE2 support, the JIT compiler
+is disabled and the VM falls back to the LuaJIT interpreter. This is faster
+than the Lua interpreter, but not nearly as fast as the JIT compiler of course.
+Run the command line executable without arguments to show the current status
+(<tt>JIT: ON</tt> or <tt>JIT: OFF</tt>).
 </li>
 <li>
 The VM is complete in the sense that it <b>should</b> run all Lua code
 just fine. It's considered a serious bug if the VM crashes or produces
-unexpected results &mdash; please report it. There are only very few
+unexpected results &mdash; please report this. There are only very few
 known incompatibilities with standard Lua:
 <ul>
 <li>
@@ -125,12 +126,12 @@ demonstrable need is shown.
 <li>
 The <b>JIT compiler</b> is not complete (yet) and falls back to the
 interpreter in some cases. All of this works transparently, so unless
-you use <tt>-jv</tt>, you'll probably never notice (the interpreter is quite
-fast, too). Here are the known issues:
+you use <tt>-jv</tt>, you'll probably never notice (the interpreter is
+<a href="http://luajit.org/performance.html"><span class="ext">&raquo;</span>&nbsp;quite fast</a>, too). Here are the known issues:
 <ul>
 <li>
-Many known issues cause a <b>NYI</b> (not yet implemented) trace abort
-message. E.g. for calls to vararg functions or many string library
+Most known issues cause a <b>NYI</b> (not yet implemented) trace abort
+message. E.g. for calls to some internal library
 functions. Reporting these is only mildly useful, except if you have good
 example code that shows the problem. Obviously, reports accompanied with
 a patch to fix the issue are more than welcome. But please check back
@@ -138,7 +139,7 @@ with me, before writing major improvements, to avoid duplication of
 effort.
 </li>
 <li>
-The trace compiler currently does not back off specialization for
+The trace compiler currently doesn't back off specialization for
 function call dispatch. It should really fall back to specializing on
 the prototype, not the closure identity. This can lead to the so-called
 "trace explosion" problem with <b>closure-heavy programming</b>. The
@@ -191,20 +192,20 @@ overriding goal for a low-footprint, low-overhead JIT compiler.
 <li>
 More <b>optimizations</b> will be added in parallel to the last step on
 an as-needed basis. Sinking of stores
-to aggregates and sinking of allocations are high on the list. Faster
-handling of NEWREF and better alias analysis are desirable, too. More
-complex optimizations with less pay-off, such as value-range-propagation
+to aggregates and sinking of allocations are high on the list.
+More complex optimizations with less pay-off, such as value-range-propagation
 (VRP) will have to wait.
 </li>
 <li>
 LuaJIT 2.0 has been designed with <b>portability</b> in mind.
 Nonetheless, it compiles to native code and needs to be adapted to each
-architecture. Porting the compiler backend is probably the easier task,
-but a key element of its design is the fast interpreter, written in
-machine-specific assembler.<br>
-An x64 port is already available, thanks to the
+architecture. The two major work items are porting the the fast interpreter,
+which is written in assembler, and porting the compiler backend.
+Most other portability issues like endianess or 32 vs. 64&nbsp;bit CPUs
+have already been taken care of.<br>
+Several ports are already available, thanks to the
 <a href="sponsors.html">LuaJIT sponsorship program</a>.
-Other ports will follow &mdash; companies which are
+More ports will follow in the future &mdash; companies which are
 interested in sponsoring a port to a particular architecture, please
 use the given contact address.
 </li>
@@ -230,9 +231,10 @@ for efficient <b>vectorization</b>.
 Currently Lua is missing a standard library for access to <b>structured
 binary data</b> and <b>arrays/buffers</b> holding low-level data types.
 Allowing calls to arbitrary C functions (<b>FFI</b>) would obviate the
-need to write manual bindings. A variety of extension modules is floating
-around, with different scope and capabilities. Alas, none of them has been
-designed with a JIT compiler in mind.
+need to write manual bindings. A variety of Lua extension modules are
+available, with different scope and capabilities. Alas, none of them has been
+designed with a JIT compiler in mind. An FFI for LuaJIT is currently
+in the design phase, but there's no ETA, yet.
 </li>
 </ul>
 <br class="flush">