From af92a143132ab8f39d9d7893fe4797b67b72bc98 Mon Sep 17 00:00:00 2001
From: Mike Pall <mike>
Date: Thu, 4 Mar 2010 19:07:38 +0100
Subject: [PATCH] Update docs: native build default, cross-compilation,
 embedding.

---
 doc/changes.html |  4 +--
 doc/install.html | 75 +++++++++++++++++++++++++++++++++---------------
 doc/luajit.html  |  6 ++--
 doc/status.html  | 14 +++++----
 4 files changed, 65 insertions(+), 34 deletions(-)

diff --git a/doc/changes.html b/doc/changes.html
index 16cda402..c733e5d1 100644
--- a/doc/changes.html
+++ b/doc/changes.html
@@ -55,9 +55,9 @@ to see whether newer versions are available.
 <div class="major" style="background: #d0d0d0;">
 <h2 id="snap">Development Snapshot</h2>
 <ul>
-<li>CPU support:
+<li>Portability:
 <ul>
-<li>Port integrated memory allocator to Linux/x64 and Windows/x64.</li>
+<li>Port integrated memory allocator to Linux/x64, Windows/x64 and OSX/x64.</li>
 <li>Port interpreter and JIT compiler to x64.</li>
 <li>Port DynASM to x64.</li>
 <li>Many 32/64 bit cleanups in the VM.</li>
diff --git a/doc/install.html b/doc/install.html
index 102f3417..727668cf 100644
--- a/doc/install.html
+++ b/doc/install.html
@@ -50,14 +50,8 @@ For the impatient (on POSIX systems):
 make &amp;&amp; sudo make install
 </pre>
 <p>
-LuaJIT currently builds out-of-the box on all popular x86 systems
-(Linux, Windows, OSX etc.). It builds and runs fine as a 32&nbsp;bit
-application under x64-based systems, too.
-</p>
-<p style="color: #00a000;">
-The x64 port of LuaJIT is still preliminary and not enabled by default.
-It only builds on Linux/x64 and Windows/x64 right now. If you want to
-give it a try, please follow the special build instructions below.
+LuaJIT currently builds out-of-the box on all popular x86 or x64 systems
+(Linux, Windows, OSX etc.).
 </p>
 
 <h2>Configuring LuaJIT</h2>
@@ -85,13 +79,8 @@ any settings.
 <p>
 Depending on your distribution, you may need to install a package for
 GCC (GCC 3.4 or later required), the development headers and/or a
-complete SDK.
-</p>
-<p>
-E.g. on a current Debian/Ubuntu, install <tt>libc6-dev</tt>
-with the package manager. Currently LuaJIT builds as a 32&nbsp;bit
-application by default, so you actually need to install <tt>libc6-dev-i386</tt>
-when building on an x64 OS.
+complete SDK. E.g. on a current Debian/Ubuntu, install <tt>libc6-dev</tt>
+with the package manager.
 </p>
 <p>
 Download the current source package (pick the .tar.gz), if you haven't
@@ -111,14 +100,9 @@ which is probably the default on your system, anyway. Simply run:
 <pre class="code">
 make
 </pre>
-<div style="color: #00a000;">
 <p>
-You can force a native x64 build on Linux/x64 with the following command:
+This always builds a native x86 or x64 binary, depending on your OS.
 </p>
-<pre class="code">
-make CC="gcc -m64"
-</pre>
-</div>
 <p>
 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
@@ -203,14 +187,12 @@ Open a "Windows SDK Command Shell" and select the x86 compiler:
 <pre class="code">
 setenv /release /x86
 </pre>
-<div style="color: #00a000;">
 <p>
 Or select the x64 compiler:
 </p>
 <pre class="code">
 setenv /release /x64
 </pre>
-</div>
 <p>
 Then <tt>cd</tt> to the directory where you've unpacked the sources
 and run these commands:
@@ -254,6 +236,53 @@ absolute path names &mdash; all modules are loaded relative to the
 directory where <tt>luajit.exe</tt> is installed
 (see <tt>src/luaconf.h</tt>).
 </p>
+
+<h2>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:
+</p>
+<p>
+You can cross-compile to a 32 bit binary on a multilib x64 OS by
+installing the multilib development pacakges (e.g. <tt>libc6-dev-i386</tt>
+on Debian/Ubuntu) and running:
+</p>
+<pre class="code">
+make CC="gcc -m32"
+</pre>
+<p>
+You can cross-compile for a Windows target on Debian/Ubuntu by
+installing the <tt>mingw32</tt> package and running:
+</p>
+<pre class="code">
+make CC="gcc -m32" CROSS=i586-mingw32msvc- TARGET_SYS=Windows
+</pre>
+
+<h2>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:
+</p>
+<ul>
+<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>
+</ul>
+<p>
+64 bit applications on OSX must be linked with these options
+(only the main executable):
+</p>
+<pre class="code">
+-pagezero_size 10000 -image_base 100000000
+</pre>
 <br class="flush">
 </div>
 <div id="foot">
diff --git a/doc/luajit.html b/doc/luajit.html
index 66032fdf..fce49a68 100644
--- a/doc/luajit.html
+++ b/doc/luajit.html
@@ -62,10 +62,8 @@ standard Lua interpreter and can be deployed as a drop-in replacement.
 </p>
 <p>
 LuaJIT offers more performance, at the expense of portability. It
-currently runs on all popular operating systems based on <b>x86 CPUs</b>
-(Linux, Windows, OSX etc.). A preliminary port to Linux/x64 and Windows/x64
-is already available (follow the <a href="install.html">build instructions</a>
-to enable it).
+currently runs on all popular operating systems based on
+<b>x86 or x64 CPUs</b> (Linux, Windows, OSX etc.).
 Other platforms will be supported in the future, based on user demand
 and sponsoring.
 </p>
diff --git a/doc/status.html b/doc/status.html
index 2d750ee1..c4d9170f 100644
--- a/doc/status.html
+++ b/doc/status.html
@@ -53,10 +53,8 @@ page.
 <span style="color: #c00000;">LuaJIT 2.0</span> is the currently active
 <span style="color: #c00000;">development branch</span>.
 It has <b>Beta Test</b> status and is still undergoing
-substantial changes. It's expected to quickly mature within the next
-months. You should definitely start to evaluate it for new projects
-right now. But deploying it in production environments is not yet
-recommended.
+substantial changes. It's maturing quickly, so you should definitely
+start to evaluate it for new projects right now.
 </p>
 
 <h2>Current Status</h2>
@@ -153,6 +151,12 @@ with <b>open upvalues aliasing</b> one of the SSA slots later on (or
 vice versa). Bonus points, if you can find a real world test case for
 this.
 </li>
+<li>
+Currently some <b>out-of-memory</b> errors from <b>on-trace code</b> are not
+handled correctly. The error may fall through an on-trace
+<tt>pcall</tt> (x86) or it may be passed on to the function set with
+<tt>lua_atpanic</tt> (x64).
+</li>
 </ul>
 </li>
 </ul>
@@ -194,7 +198,7 @@ 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>
-A preliminary x64 port is already available, thanks to the
+An x64 port is already available, thanks to the
 <a href="sponsors.html">LuaJIT sponsorship program</a>.
 Other ports will follow &mdash; companies which are
 interested in sponsoring a port to a particular architecture, please