mirror of
https://github.com/LuaJIT/LuaJIT.git
synced 2025-02-07 15:14:08 +00:00
Documentation cleanup.
This commit is contained in:
Mike Pall
parent
56c04accf9
commit
ee855749a1
61
doc/faq.html
61
doc/faq.html
@ -78,16 +78,14 @@ has information about diverse topics.</li>
|
||||
<dl id="tech">
|
||||
<dt>Q: Where can I learn more about the compiler technology used by LuaJIT?</dt>
|
||||
<dd>
|
||||
I'm planning to write more documentation about the internals of LuaJIT.
|
||||
In the meantime, please use the following Google Scholar searches
|
||||
to find relevant papers:<br>
|
||||
Please use the following Google Scholar searches to find relevant papers:<br>
|
||||
Search for: <a href="https://scholar.google.com/scholar?q=Trace+Compiler"><span class="ext">»</span> Trace Compiler</a><br>
|
||||
Search for: <a href="https://scholar.google.com/scholar?q=JIT+Compiler"><span class="ext">»</span> JIT Compiler</a><br>
|
||||
Search for: <a href="https://scholar.google.com/scholar?q=Dynamic+Language+Optimizations"><span class="ext">»</span> Dynamic Language Optimizations</a><br>
|
||||
Search for: <a href="https://scholar.google.com/scholar?q=SSA+Form"><span class="ext">»</span> SSA Form</a><br>
|
||||
Search for: <a href="https://scholar.google.com/scholar?q=Linear+Scan+Register+Allocation"><span class="ext">»</span> Linear Scan Register Allocation</a><br>
|
||||
Here is a list of the <a href="http://lua-users.org/lists/lua-l/2009-11/msg00089.html"><span class="ext">»</span> innovative features in LuaJIT</a>.<br>
|
||||
And, you know, reading the source is of course the only way to enlightenment. :-)
|
||||
And, you know, reading the source is of course the only way to enlightenment.
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
@ -126,12 +124,11 @@ Please check the Delphi docs for the Set8087CW method.
|
||||
<dl id="ctrlc">
|
||||
<dt>Q: Sometimes Ctrl-C fails to stop my Lua program. Why?</dt>
|
||||
<dd>The interrupt signal handler sets a Lua debug hook. But this is
|
||||
currently ignored by compiled code (this will eventually be fixed). If
|
||||
your program is running in a tight loop and never falls back to the
|
||||
interpreter, the debug hook never runs and can't throw the
|
||||
"interrupted!" error.<br> In the meantime you have to press Ctrl-C
|
||||
twice to get stop your program. That's similar to when it's stuck
|
||||
running inside a C function under the Lua interpreter.</dd>
|
||||
ignored by compiled code. If your program is running in a tight loop
|
||||
and never falls back to the interpreter, the debug hook never runs and
|
||||
can't throw the "interrupted!" error.<br>
|
||||
You have to press Ctrl-C twice to get stop your program. That's similar
|
||||
to when it's stuck running inside a C function under the Lua interpreter.</dd>
|
||||
</dl>
|
||||
|
||||
<dl id="sandbox">
|
||||
@ -145,30 +142,20 @@ it's very hard to get this right even for the Lua core libraries. Of course,
|
||||
you'll need to inspect any extension library, too. And there are libraries
|
||||
that are inherently unsafe, e.g. the <a href="ext_ffi.html">FFI library</a>.<br>
|
||||
|
||||
Relatedly, <b>loading untrusted bytecode is not safe!</b> It's trivial
|
||||
to crash the Lua or LuaJIT VM with maliciously crafted bytecode. This is
|
||||
well known and there's no bytecode verification on purpose, so please
|
||||
More reading material at the <a href="http://lua-users.org/wiki/SandBoxes"><span class="ext">»</span> Lua Wiki</a> and <a href="https://en.wikipedia.org/wiki/Sandbox_(computer_security)"><span class="ext">»</span> Wikipedia</a>.<br><br>
|
||||
|
||||
Relatedly, <b>loading untrusted bytecode is not safe!</b><br>
|
||||
|
||||
It's trivial to crash the Lua or LuaJIT VM with maliciously crafted bytecode.
|
||||
This is well known and there's no bytecode verification on purpose, so please
|
||||
don't report a bug about it. Check the <tt>mode</tt> parameter for the
|
||||
<tt>load*()</tt> functions to disable loading of bytecode.<br>
|
||||
<tt>load*()</tt> functions to disable loading of bytecode.<br><br>
|
||||
|
||||
In general, the only promising approach is to sandbox Lua code at the
|
||||
process level and not the VM level.<br>
|
||||
|
||||
More reading material at the <a href="http://lua-users.org/wiki/SandBoxes"><span class="ext">»</span> Lua Wiki</a> and <a href="https://en.wikipedia.org/wiki/Sandbox_(computer_security)"><span class="ext">»</span> Wikipedia</a>.
|
||||
<b>In general, the only promising approach is to sandbox Lua code at the
|
||||
process level and not the VM level.</b>
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
<dl id="patches">
|
||||
<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, 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.
|
||||
The compiler will happily optimize away such indirections.</dd>
|
||||
</dl>
|
||||
|
||||
<dl id="arch">
|
||||
<dt>Q: Lua runs everywhere. Why doesn't LuaJIT support my CPU?</dt>
|
||||
<dd>Because it's a compiler — it needs to generate native
|
||||
@ -176,17 +163,11 @@ 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>
|
||||
The <a href="install.html">install documentation</a> shows the supported
|
||||
architectures. Other architectures will follow based on sufficient user
|
||||
demand and/or sponsoring.</dd>
|
||||
</dl>
|
||||
|
||||
<dl id="when">
|
||||
<dt>Q: When will feature X be added? When will the next version be released?</dt>
|
||||
<dd>When it's ready.<br>
|
||||
C'mon, it's open source — I'm doing it on my own time and you're
|
||||
getting it for free. You can either contribute a patch or sponsor
|
||||
the development of certain features, if they are important to you.
|
||||
</dd>
|
||||
architectures.<br>
|
||||
Other architectures may follow based on sufficient user demand and
|
||||
market-relevance of the architecture. Sponsoring is required to develop
|
||||
the port itself, to integrate it and to continuously maintain it in the
|
||||
actively developed branches.</dd>
|
||||
</dl>
|
||||
<br class="flush">
|
||||
</div>
|
||||
|
||||
@ -101,8 +101,8 @@ operating systems, CPUs and compilers:
|
||||
<td class="compatcpu">CPU / OS</td>
|
||||
<td class="compatos"><a href="#posix">Linux</a> or<br><a href="#android">Android</a></td>
|
||||
<td class="compatos"><a href="#posix">*BSD, Other</a></td>
|
||||
<td class="compatos"><a href="#posix">OSX 10.4+</a> or<br><a href="#ios">iOS 3.0+</a></td>
|
||||
<td class="compatos"><a href="#windows">Windows<br>XP/Vista/7</a></td>
|
||||
<td class="compatos"><a href="#posix">macOS 10.4+</a> or<br><a href="#ios">iOS 3.0+</a></td>
|
||||
<td class="compatos"><a href="#windows">Windows XP<br>or later</a></td>
|
||||
</tr>
|
||||
<tr class="odd separate">
|
||||
<td class="compatcpu">x86 (32 bit)</td>
|
||||
@ -168,7 +168,7 @@ Please read the instructions given in these files, before changing
|
||||
any settings.
|
||||
</p>
|
||||
|
||||
<h2 id="posix">POSIX Systems (Linux, OSX, *BSD etc.)</h2>
|
||||
<h2 id="posix">POSIX Systems (Linux, macOS, *BSD etc.)</h2>
|
||||
<h3>Prerequisites</h3>
|
||||
<p>
|
||||
Depending on your distribution, you may need to install a package for
|
||||
@ -176,8 +176,9 @@ GCC, the development headers and/or a 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 of LuaJIT (pick the .tar.gz),
|
||||
if you haven't already done so. Move it to a directory of your choice,
|
||||
The recommended way to fetch the latest version is to do a pull from
|
||||
the git repository. Alternatively download the latest source package of
|
||||
LuaJIT (pick the .tar.gz). Move it to a directory of your choice,
|
||||
open a terminal window and change to this directory. Now unpack the archive
|
||||
and change to the newly created directory:
|
||||
</p>
|
||||
@ -207,7 +208,7 @@ You can add an extra prefix to the search paths by appending the
|
||||
make PREFIX=/home/myself/lj2
|
||||
</pre>
|
||||
<p>
|
||||
Note for OSX: you must set the <tt>MACOSX_DEPLOYMENT_TARGET</tt>
|
||||
Note for macOS: you must set the <tt>MACOSX_DEPLOYMENT_TARGET</tt>
|
||||
environment variable to a value supported by your toolchain.
|
||||
</p>
|
||||
<h3>Installing LuaJIT</h3>
|
||||
@ -241,8 +242,9 @@ GCC plus the required development headers.
|
||||
Or install Microsoft's Visual Studio (MSVC).
|
||||
</p>
|
||||
<p>
|
||||
Next, download the source package and unpack it using an archive manager
|
||||
(e.g. the Windows Explorer) to a directory of your choice.
|
||||
Next, pull from the git repository or download the source package and
|
||||
unpack it using an archive manager (e.g. the Windows Explorer) to
|
||||
a directory of your choice.
|
||||
</p>
|
||||
<h3>Building with MSVC</h3>
|
||||
<p>
|
||||
@ -260,8 +262,8 @@ Then follow the installation instructions below.
|
||||
<h3>Building with MinGW or Cygwin</h3>
|
||||
<p>
|
||||
Open a command prompt window and make sure the MinGW or Cygwin programs
|
||||
are in your path. Then <tt>cd</tt> to the directory where
|
||||
you've unpacked the sources and run this command for MinGW:
|
||||
are in your path. Then <tt>cd</tt> to the directory of the git repository
|
||||
or where you've unpacked the sources. Then run this command for MinGW:
|
||||
</p>
|
||||
<pre class="code">
|
||||
mingw32-make
|
||||
@ -302,7 +304,7 @@ x64 OS, you need to install the multilib development package (e.g.
|
||||
<p>
|
||||
You need to specify <tt>TARGET_SYS</tt> whenever the host OS and the
|
||||
target OS differ, or you'll get assembler or linker errors. E.g. if
|
||||
you're compiling on a Windows or OSX host for embedded Linux or Android,
|
||||
you're compiling on a Windows or macOS host for embedded Linux or Android,
|
||||
you need to add <tt>TARGET_SYS=Linux</tt> to the examples below. For a
|
||||
minimal target OS, you may need to disable the built-in allocator in
|
||||
<tt>src/Makefile</tt> and use <tt>TARGET_SYS=Other</tt>. Don't forget to
|
||||
@ -461,15 +463,14 @@ 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
|
||||
<i>Important: this relates to LuaJIT 2.0 only — use LuaJIT 2.1 to
|
||||
avoid these complications.</i><br>
|
||||
If you're building a 64 bit application on macOS 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>
|
||||
@ -479,7 +480,7 @@ See: <tt>man rebase</tt>
|
||||
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).</li>
|
||||
allocator from your system (no support for this on 64 bit architectures).</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 or extend the list of standard libraries to load, copy
|
||||
|
||||
@ -152,7 +152,7 @@ LuaJIT is Copyright © 2005-2020 Mike Pall, released under the
|
||||
|
||||
<h2>Compatibility</h2>
|
||||
<table class="feature os os1">
|
||||
<tr><td>Windows</td><td>Linux</td><td>BSD</td><td>OSX</td><td>POSIX</td></tr>
|
||||
<tr><td>Windows</td><td>Linux</td><td>BSD</td><td>macOS</td><td>POSIX</td></tr>
|
||||
</table>
|
||||
<table class="feature os os2">
|
||||
<tr><td><span style="font-size:90%;">Embedded</span></td><td>Android</td><td>iOS</td></tr>
|
||||
|
||||
@ -56,9 +56,15 @@ ul li { padding-bottom: 0.3em; }
|
||||
</div>
|
||||
<div id="main">
|
||||
<p>
|
||||
<span style="color: #0000c0;">LuaJIT 2.0</span> is the current
|
||||
<span style="color: #0000c0;">stable branch</span>. This branch is in
|
||||
feature-freeze — new features will only be added to LuaJIT 2.1.
|
||||
This documentation is for LuaJIT 2.0.5. Please check the <tt>doc</tt>
|
||||
directory in each git branch for the version-specific documentation.
|
||||
</p>
|
||||
<p>
|
||||
The currently developed branches are LuaJIT 2.1 and LuaJIT 2.0.
|
||||
</p>
|
||||
<p>
|
||||
LuaJIT 2.0 is in feature-freeze — new features will only
|
||||
be added to LuaJIT 2.1.
|
||||
</p>
|
||||
|
||||
<h2>Current Status</h2>
|
||||
@ -86,8 +92,7 @@ in LuaJIT (no per-coroutine hooks, no tail call counting).
|
||||
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> or it may be passed on to the function set with
|
||||
<tt>lua_atpanic</tt> on x64. This issue will be fixed with the new
|
||||
garbage collector.
|
||||
<tt>lua_atpanic</tt> on x64.
|
||||
</li>
|
||||
</ul>
|
||||
<br class="flush">
|
||||
|
||||
Loading…
Reference in New Issue
Block a user