From ee855749a188d3d13bba9a0e58f430e138e641ae Mon Sep 17 00:00:00 2001 From: Mike Pall Date: Sat, 2 Jan 2021 21:17:01 +0100 Subject: [PATCH] Documentation cleanup. --- doc/faq.html | 61 +++++++++++++++++------------------------------- doc/install.html | 33 +++++++++++++------------- doc/luajit.html | 2 +- doc/status.html | 15 ++++++++---- 4 files changed, 49 insertions(+), 62 deletions(-) diff --git a/doc/faq.html b/doc/faq.html index a7144670..843480fc 100644 --- a/doc/faq.html +++ b/doc/faq.html @@ -78,16 +78,14 @@ has information about diverse topics.
Q: Where can I learn more about the compiler technology used by LuaJIT?
-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:
+Please use the following Google Scholar searches to find relevant papers:
Search for: » Trace Compiler
Search for: » JIT Compiler
Search for: » Dynamic Language Optimizations
Search for: » SSA Form
Search for: » Linear Scan Register Allocation
Here is a list of the » innovative features in LuaJIT.
-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.
@@ -126,12 +124,11 @@ Please check the Delphi docs for the Set8087CW method.
Q: Sometimes Ctrl-C fails to stop my Lua program. Why?
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.
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.
+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.
+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.
@@ -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 FFI library.
-Relatedly, loading untrusted bytecode is not safe! 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 » Lua Wiki and » Wikipedia.

+ +Relatedly, loading untrusted bytecode is not safe!
+ +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 mode parameter for the -load*() functions to disable loading of bytecode.
+load*() functions to disable loading of bytecode.

-In general, the only promising approach is to sandbox Lua code at the -process level and not the VM level.
- -More reading material at the » Lua Wiki and » Wikipedia. +In general, the only promising approach is to sandbox Lua code at the +process level and not the VM level.
-
-
Q: Why doesn't my favorite power-patch for Lua apply against LuaJIT?
-
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.
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.
-
-
Q: Lua runs everywhere. Why doesn't LuaJIT support my CPU?
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.
The install documentation shows the supported -architectures. Other architectures will follow based on sufficient user -demand and/or sponsoring.
-
- -
-
Q: When will feature X be added? When will the next version be released?
-
When it's ready.
-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. -
+architectures.
+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.

diff --git a/doc/install.html b/doc/install.html index 85ca9913..6110450c 100644 --- a/doc/install.html +++ b/doc/install.html @@ -101,8 +101,8 @@ operating systems, CPUs and compilers: CPU / OS Linux or
Android *BSD, Other -OSX 10.4+ or
iOS 3.0+ -Windows
XP/Vista/7 +macOS 10.4+ or
iOS 3.0+ +Windows XP
or later x86 (32 bit) @@ -168,7 +168,7 @@ Please read the instructions given in these files, before changing any settings.

-

POSIX Systems (Linux, OSX, *BSD etc.)

+

POSIX Systems (Linux, macOS, *BSD etc.)

Prerequisites

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 libc6-dev with the package manager.

-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:

@@ -207,7 +208,7 @@ You can add an extra prefix to the search paths by appending the make PREFIX=/home/myself/lj2

-Note for OSX: you must set the MACOSX_DEPLOYMENT_TARGET +Note for macOS: you must set the MACOSX_DEPLOYMENT_TARGET environment variable to a value supported by your toolchain.

Installing LuaJIT

@@ -241,8 +242,9 @@ GCC plus the required development headers. Or install Microsoft's Visual Studio (MSVC).

-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.

Building with MSVC

@@ -260,8 +262,8 @@ Then follow the installation instructions below.

Building with MinGW or Cygwin

Open a command prompt window and make sure the MinGW or Cygwin programs -are in your path. Then cd to the directory where -you've unpacked the sources and run this command for MinGW: +are in your path. Then cd to the directory of the git repository +or where you've unpacked the sources. Then run this command for MinGW: 

 mingw32-make
@@ -302,7 +304,7 @@ x64 OS, you need to install the multilib development package (e.g.
 

 You need to specify TARGET_SYS 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 TARGET_SYS=Linux to the examples below. For a
 minimal target OS, you may need to disable the built-in allocator in
 src/Makefile and use TARGET_SYS=Other. Don't forget to
@@ -461,15 +463,14 @@ intend to load Lua/C modules at runtime.
 
 
 
  • 
-If you're building a 64 bit application on OSX which links directly or
+Important: this relates to LuaJIT 2.0 only — use LuaJIT 2.1 to
+avoid these complications.
    
+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:
 
     -pagezero_size 10000 -image_base 100000000
 
    
-Also, it's recommended to rebase all (self-compiled) shared libraries
-which are loaded at runtime on OSX/x64 (e.g. C extension modules for Lua).
-See: man rebase
 
    • 
 
 
    Additional hints for initializing LuaJIT using the C API functions:
    
@@ -479,7 +480,7 @@ See: man rebase
 for embedding Lua or LuaJIT into your application.
 
  • Make sure you use luaL_newstate. Avoid using
 lua_newstate, since this uses the (slower) default memory
-allocator from your system (no support for this on x64).
    • 
+allocator from your system (no support for this on 64 bit architectures).
 
  • Make sure you use luaL_openlibs and not the old Lua 5.0 style
 of calling luaopen_base etc. directly.
    • 
 
  • To change or extend the list of standard libraries to load, copy
diff --git a/doc/luajit.html b/doc/luajit.html
index f99aa022..d5b1c1e6 100644
--- a/doc/luajit.html
+++ b/doc/luajit.html
@@ -152,7 +152,7 @@ LuaJIT is Copyright © 2005-2020 Mike Pall, released under the
 
 
    Compatibility
    
 
-
+
    WindowsLinuxBSDOSXPOSIX
    WindowsLinuxBSDmacOSPOSIX
    
 
    
 
diff --git a/doc/status.html b/doc/status.html
index 0d357613..d28d7eb5 100644
--- a/doc/status.html
+++ b/doc/status.html
@@ -56,9 +56,15 @@ ul li { padding-bottom: 0.3em; }
 
    
 
    
-LuaJIT 2.0 is the current
-stable branch. 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 doc
+directory in each git branch for the version-specific documentation.
+
    
+
    
+The currently developed branches are LuaJIT 2.1 and LuaJIT 2.0.
+
    
+
    
+LuaJIT 2.0 is in feature-freeze — new features will only
+be added to LuaJIT 2.1.
 
    
 
 
    Current Status
    
@@ -86,8 +92,7 @@ in LuaJIT (no per-coroutine hooks, no tail call counting).
 Currently some out-of-memory errors from on-trace code are not
 handled correctly. The error may fall through an on-trace
 pcall or it may be passed on to the function set with
-lua_atpanic on x64. This issue will be fixed with the new
-garbage collector.
+lua_atpanic on x64.
 
 
 
    

    
 
    EmbeddedAndroidiOS