diff options
Diffstat (limited to 'libs/luajit-cmake/luajit/doc/install.html')
| -rw-r--r-- | libs/luajit-cmake/luajit/doc/install.html | 776 |
1 files changed, 776 insertions, 0 deletions
diff --git a/libs/luajit-cmake/luajit/doc/install.html b/libs/luajit-cmake/luajit/doc/install.html new file mode 100644 index 0000000..d78dda3 --- /dev/null +++ b/libs/luajit-cmake/luajit/doc/install.html @@ -0,0 +1,776 @@ +<!DOCTYPE html> +<html> +<head> +<title>Installation</title> +<meta charset="utf-8"> +<meta name="Copyright" content="Copyright (C) 2005-2022"> +<meta name="Language" content="en"> +<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen"> +<link rel="stylesheet" type="text/css" href="bluequad-print.css" media="print"> +<style type="text/css"> +table.compat { + line-height: 1.2; + font-size: 80%; +} +table.compat td { + border: 1px solid #bfcfff; + height: 1.5em; +} +table.compat tr.compathead td { + font-weight: bold; + border-bottom: 2px solid #bfcfff; +} +td.compatname, td.compatver { + width: 10%; +} +td.compatbits { + width: 5%; +} +td.compatx { + width: 21%; +} +</style> +</head> +<body> +<div id="site"> +<a href="https://luajit.org"><span>Lua<span id="logo">JIT</span></span></a> +</div> +<div id="head"> +<h1>Installation</h1> +</div> +<div id="nav"> +<ul><li> +<a href="luajit.html">LuaJIT</a> +<ul><li> +<a href="https://luajit.org/download.html">Download <span class="ext">»</span></a> +</li><li> +<a class="current" href="install.html">Installation</a> +</li><li> +<a href="running.html">Running</a> +</li></ul> +</li><li> +<a href="extensions.html">Extensions</a> +<ul><li> +<a href="ext_ffi.html">FFI Library</a> +<ul><li> +<a href="ext_ffi_tutorial.html">FFI Tutorial</a> +</li><li> +<a href="ext_ffi_api.html">ffi.* API</a> +</li><li> +<a href="ext_ffi_semantics.html">FFI Semantics</a> +</li></ul> +</li><li> +<a href="ext_buffer.html">String Buffers</a> +</li><li> +<a href="ext_jit.html">jit.* Library</a> +</li><li> +<a href="ext_c_api.html">Lua/C API</a> +</li><li> +<a href="ext_profiler.html">Profiler</a> +</li></ul> +</li><li> +<a href="status.html">Status</a> +</li><li> +<a href="faq.html">FAQ</a> +</li><li> +<a href="https://luajit.org/list.html">Mailing List <span class="ext">»</span></a> +</li></ul> +</div> +<div id="main"> +<p> +LuaJIT is only distributed as a source package. This page explains +how to build and install LuaJIT with different operating systems +and C compilers. +</p> +<p> +For the impatient (on POSIX systems): +</p> +<pre class="code"> +make && sudo make install +</pre> + +<h2 id="req">Requirements</h2> +<h3 id="systems">Systems</h3> +<p> +LuaJIT currently builds out-of-the box on most systems: +</p> +<table class="compat"> +<tr class="compathead"> +<td class="compatname">OS</td> +<td class="compatver">Min. Version</td> +<td class="compatx">Requirements</td> +<td class="compatx">LuaJIT Versions</td> +</tr> +<tr class="odd separate"> +<td class="compatname"><a href="#windows">Windows</a></td> +<td class="compatver">7</td> +<td class="compatx">x86 or x64, ARM64: TBA</td> +<td class="compatx">v2.0 –</td> +</tr> +<tr class="even"> +<td class="compatname"><a href="#posix">Linux</a></td> +<td class="compatver"> </td> +<td class="compatx"> </td> +<td class="compatx">v2.0 –</td> +</tr> +<tr class="odd"> +<td class="compatname"><a href="#posix">*BSD</a></td> +<td class="compatver"> </td> +<td class="compatx"> </td> +<td class="compatx">v2.0 –</td> +</tr> +<tr class="even"> +<td class="compatname"><a href="#posix">macOS (OSX)</a></td> +<td class="compatver">10.4</td> +<td class="compatx"> </td> +<td class="compatx">v2.1 –</td> +</tr> +<tr class="odd"> +<td class="compatname"><a href="#posix">POSIX</a></td> +<td class="compatver"> </td> +<td class="compatx">mmap, dlopen</td> +<td class="compatx">v2.0 –</td> +</tr> +<tr class="even separate"> +<td class="compatname"><a href="#android">Android</a></td> +<td class="compatver">4.0</td> +<td class="compatx">Recent Android NDK</td> +<td class="compatx">v2.0 –</td> +</tr> +<tr class="odd"> +<td class="compatname"><a href="#ios">iOS</a></td> +<td class="compatver">3.0</td> +<td class="compatx">Xcode iOS SDK</td> +<td class="compatx">v2.1 –</td> +</tr> +<tr class="even separate"> +<td class="compatname"><a href="#consoles">PS3</a></td> +<td class="compatver"> </td> +<td class="compatx">PS3 SDK</td> +<td class="compatx">v2.0 – v2.1 EOL</td> +</tr> +<tr class="odd"> +<td class="compatname"><a href="#consoles">PS4</a></td> +<td class="compatver"> </td> +<td class="compatx">PS4 SDK (ORBIS)</td> +<td class="compatx">v2.0 –</td> +</tr> +<tr class="even"> +<td class="compatname"><a href="#consoles">PS5</a></td> +<td class="compatver"> </td> +<td class="compatx">PS5 SDK (PROSPERO)</td> +<td class="compatx">v2.1 –</td> +</tr> +<tr class="odd"> +<td class="compatname"><a href="#consoles">PS Vita</a></td> +<td class="compatver"> </td> +<td class="compatx">PS Vita SDK (PSP2)</td> +<td class="compatx">v2.0 – v2.1 EOL</td> +</tr> +<tr class="even"> +<td class="compatname"><a href="#consoles">Xbox 360</a></td> +<td class="compatver"> </td> +<td class="compatx">Xbox 360 SDK (XEDK)</td> +<td class="compatx">v2.0 – v2.1 EOL</td> +</tr> +<tr class="odd"> +<td class="compatname"><a href="#consoles">Xbox One</a></td> +<td class="compatver"> </td> +<td class="compatx">Xbox One SDK (DURANGO)</td> +<td class="compatx">v2.1 –</td> +</tr> +<tr class="even"> +<td class="compatname"><a href="#consoles">Nintendo Switch</a></td> +<td class="compatver"> </td> +<td class="compatx">NintendoSDK + NX Addon</td> +<td class="compatx">v2.1 –</td> +</tr> +</table> +<p> +The codebase has compatibility defines for some more systems, but +without official support. +</p> +<h3 id="toolchains">Toolchains</h3> +<p> +Building LuaJIT requires a recent toolchain based on GCC, Clang/LLVM or +MSVC++. +</p> +<p> +The Makefile-based build system requires GNU Make and supports +cross-builds. Batch files are provided for MSVC++ builds and console +cross-builds. +</p> +<h3 id="architectures">CPU Architectures</h3> +<table class="compat"> +<tr class="compathead"> +<td class="compatname">CPU</td> +<td class="compatbits">Bits</td> +<td class="compatx">Requirements</td> +<td class="compatx">Variants</td> +<td class="compatx">LuaJIT Versions</td> +</tr> +<tr class="odd separate"> +<td class="compatname">x86</td> +<td class="compatbits">32</td> +<td class="compatx">v2.1+: SSE2</td> +<td class="compatx"> </td> +<td class="compatx">v2.0 –</td> +</tr> +<tr class="even"> +<td class="compatname">x64</td> +<td class="compatbits">64</td> +<td class="compatx"> </td> +<td class="compatx"> </td> +<td class="compatx">v2.0 –</td> +</tr> +<tr class="odd"> +<td class="compatname">ARM</td> +<td class="compatbits">32</td> +<td class="compatx">ARMv5+, ARM9E+</td> +<td class="compatx">hard-fp + soft-fp</td> +<td class="compatx">v2.0 –</td> +</tr> +<tr class="even"> +<td class="compatname">ARM64</td> +<td class="compatbits">64</td> +<td class="compatx"> </td> +<td class="compatx">ARM64le + ARM64be</td> +<td class="compatx">v2.1 –</td> +</tr> +<tr class="odd"> +<td class="compatname">PPC32</td> +<td class="compatbits">32</td> +<td class="compatx"> </td> +<td class="compatx">hard-fp + soft-fp</td> +<td class="compatx">v2.0 – v2.1 EOL</td> +</tr> +<tr class="even"> +<td class="compatname">PPC/e500</td> +<td class="compatbits">32</td> +<td class="compatx">e500v2</td> +<td class="compatx"> </td> +<td class="compatx">v2.0 EOL</td> +</tr> +<tr class="odd"> +<td class="compatname">MIPS32</td> +<td class="compatbits">32</td> +<td class="compatx">MIPS32r1 – r5</td> +<td class="compatx">hard-fp + soft-fp</td> +<td class="compatx">v2.0 –</td> +</tr> +<tr class="even"> +<td class="compatname">MIPS64</td> +<td class="compatbits">64</td> +<td class="compatx">MIPS64r1 – r5</td> +<td class="compatx">hard-fp + soft-fp</td> +<td class="compatx">v2.1 –</td> +</tr> +<tr class="odd"> +<td class="compatname">MIPS64</td> +<td class="compatbits">64</td> +<td class="compatx">MIPS64r6</td> +<td class="compatx">hard-fp + soft-fp</td> +<td class="compatx">v2.1 EOL</td> +</tr> +<tr class="even"> +<td class="compatname">RISC-V</td> +<td class="compatbits">64</td> +<td class="compatx">RVA22+</td> +<td class="compatx"> </td> +<td class="compatx">TBA</td> +</tr> +</table> +<p> +There are no plans to add historic architectures or to continue support +for end-of-life (EOL) architectures, for which no new CPUs are commonly +available anymore. Likewise, there are no plans to support marginal +and/or de-facto-dead architectures. +</p> + +<h2>Configuring LuaJIT</h2> +<p> +The standard configuration should work fine for most installations. +Usually there is no need to tweak the settings. The following files +hold all user-configurable settings: +</p> +<ul> +<li><tt>src/luaconf.h</tt> sets some configuration variables.</li> +<li><tt>Makefile</tt> has settings for <b>installing</b> LuaJIT (POSIX +only).</li> +<li><tt>src/Makefile</tt> has settings for <b>compiling</b> LuaJIT +under POSIX, MinGW or Cygwin.</li> +<li><tt>src/msvcbuild.bat</tt> has settings for compiling LuaJIT with +MSVC (Visual Studio).</li> +</ul> +<p> +Please read the instructions given in these files, before changing +any settings. +</p> +<p> +All LuaJIT 64 bit ports use 64 bit GC objects by default (<tt>LJ_GC64</tt>). +For x64, you can select the old 32-on-64 bit mode by adding +<tt>XCFLAGS=-DLUAJIT_DISABLE_GC64</tt> to the make command. +Please check the note about the +<a href="extensions.html#string_dump">bytecode format</a> differences, too. +</p> + +<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 +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> +The recommended way to fetch the latest version is to do a pull from +the git repository. +</p> +<p> +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 (replace XX.YY.ZZ with the version you downloaded): +</p> +<pre class="code"> +tar zxf LuaJIT-XX.YY.ZZ.tar.gz +cd LuaJIT-XX.YY.ZZ +</pre> +<h3>Building LuaJIT</h3> +<p> +The supplied Makefiles try to auto-detect the settings needed for your +operating system and your compiler. They need to be run with GNU Make, +which is probably the default on your system, anyway. Simply run: +</p> +<pre class="code"> +make +</pre> +<p> +This always builds a native 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>. +You can add an extra prefix to the search paths by appending the +<tt>PREFIX</tt> option, e.g.: +</p> +<pre class="code"> +make PREFIX=/home/myself/lj2 +</pre> +<p> +Note for macOS: you <b>must</b> set the <tt>MACOSX_DEPLOYMENT_TARGET</tt> +environment variable to a value supported by your toolchain: +</p> +<pre class="code"> +MACOSX_DEPLOYMENT_TARGET=XX.YY make +</pre> +<h3>Installing LuaJIT</h3> +<p> +The top-level Makefile installs LuaJIT by default under +<tt>/usr/local</tt>, i.e. the executable ends up in +<tt>/usr/local/bin</tt> and so on. You need root privileges +to write to this path. So, assuming sudo is installed on your system, +run the following command and enter your sudo password: +</p> +<pre class="code"> +sudo make install +</pre> +<p> +Otherwise specify the directory prefix as an absolute path, e.g.: +</p> +<pre class="code"> +make install PREFIX=/home/myself/lj2 +</pre> +<p> +Obviously the prefixes given during build and installation need to be the same. +</p> + +<h2 id="windows">Windows Systems</h2> +<h3>Prerequisites</h3> +<p> +Either install one of the open source SDKs +(<a href="http://mingw.org/"><span class="ext">»</span> MinGW</a> or +<a href="https://www.cygwin.com/"><span class="ext">»</span> Cygwin</a>), which come with a modified +GCC plus the required development headers. +Or install Microsoft's Visual Studio (MSVC). +</p> +<p> +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> +Open a "Visual Studio Command Prompt" (either x86 or x64), <tt>cd</tt> to the +directory where you've unpacked the sources and run these commands: +</p> +<pre class="code"> +cd src +msvcbuild +</pre> +<p> +Check the <tt>msvcbuild.bat</tt> file for more options. +Then follow the installation instructions below. +</p> +<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 of the git repository +or where you've unpacked the sources. Then run this command for MinGW: +</p> +<pre class="code"> +mingw32-make +</pre> +<p> +Or this command for Cygwin: +</p> +<pre class="code"> +make +</pre> +<p> +Then follow the installation instructions below. +</p> +<h3>Installing LuaJIT</h3> +<p> +Copy <tt>luajit.exe</tt> and <tt>lua51.dll</tt> (built in the <tt>src</tt> +directory) to a newly created directory (any location is ok). +Add <tt>lua</tt> and <tt>lua\jit</tt> directories below it and copy +all Lua files from the <tt>src\jit</tt> directory of the distribution +to the latter directory. +</p> +<p> +There are no hardcoded +absolute path names — all modules are loaded relative to the +directory where <tt>luajit.exe</tt> is installed +(see <tt>src/luaconf.h</tt>). +</p> + +<h2 id="cross">Cross-compiling LuaJIT</h2> +<p> +First, let's clear up some terminology: +</p> +<ul> +<li>Host: This is your development system, usually based on a x64 or x86 CPU.</li> +<li>Target: This is the target system you want LuaJIT to run on, e.g. Android/ARM.</li> +<li>Toolchain: This comprises a C compiler, linker, assembler and a matching C library.</li> +<li>Host (or system) toolchain: This is the toolchain used to build native binaries for your host system.</li> +<li>Cross-compile toolchain: This is the toolchain used to build binaries for the target system. They can only be run on the target system.</li> +</ul> +<p> +The GNU Makefile-based build system allows cross-compiling on any host +for any supported target: +</p> +<ul> +<li>Yes, you need a toolchain for both your host <em>and</em> your target!</li> +<li>Both host and target architectures must have the same pointer size.</li> +<li>E.g. if you want to cross-compile to a 32 bit target on a 64 bit host, you need to install the multilib development package (e.g. <tt>libc6-dev-i386</tt> on Debian/Ubuntu) and build a 32 bit host part (<tt>HOST_CC="gcc -m32"</tt>).</li> +<li>64 bit targets always require compilation on a 64 bit host.</li> +</ul> +<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: +</p> +<ul> +<li>E.g. if 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.</li> +<li>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>.</li> +<li>Don't forget to specify the same <tt>TARGET_SYS</tt> for the install step, too.</li> +</ul> +<p> +Here are some examples where host and target have the same CPU: +</p> +<pre class="code"> +# Cross-compile to a 32 bit binary on a multilib x64 OS +make CC="gcc -m32" + +# Cross-compile on Debian/Ubuntu for Windows (mingw32 package) +make HOST_CC="gcc -m32" CROSS=i586-mingw32msvc- TARGET_SYS=Windows +</pre> +<p id="cross2"> +The <tt>CROSS</tt> prefix allows specifying a standard GNU cross-compile +toolchain (Binutils, GCC and a matching libc). The prefix may vary +depending on the <tt>--target</tt> the toolchain was built for (note the +<tt>CROSS</tt> prefix has a trailing <tt>"-"</tt>). The examples below +use the canonical toolchain triplets for Linux. +</p> +<p> +Since there's often no easy way to detect CPU features at runtime, it's +important to compile with the proper CPU or architecture settings: +</o> +<ul> +<li>The best way to get consistent results is to specify the correct settings when building the toolchain yourself.</li> +<li>For a pre-built, generic toolchain add <tt>-mcpu=...</tt> or <tt>-march=...</tt> and other necessary flags to <tt>TARGET_CFLAGS</tt>.</li> +<li>For ARM it's important to have the correct <tt>-mfloat-abi=...</tt> setting, too. Otherwise LuaJIT may not run at the full performance of your target CPU.</li> +<li>For MIPS it's important to select a supported ABI (o32 on MIPS32, n64 on MIPS64) and consistently compile your project either with hard-float or soft-float compiler settings.</li> +</ul> +<p> +Here are some examples for targets with a different CPU than the host: +</p> +<pre class="code"> +# ARM soft-float +make HOST_CC="gcc -m32" CROSS=arm-linux-gnueabi- \ + TARGET_CFLAGS="-mfloat-abi=soft" + +# ARM soft-float ABI with VFP (example for Cortex-A9) +make HOST_CC="gcc -m32" CROSS=arm-linux-gnueabi- \ + TARGET_CFLAGS="-mcpu=cortex-a9 -mfloat-abi=softfp" + +# ARM hard-float ABI with VFP (armhf, most modern toolchains) +make HOST_CC="gcc -m32" CROSS=arm-linux-gnueabihf- + +# ARM64 +make CROSS=aarch64-linux- + +# PPC +make HOST_CC="gcc -m32" CROSS=powerpc-linux-gnu- + +# MIPS32 big-endian +make HOST_CC="gcc -m32" CROSS=mips-linux- +# MIPS32 little-endian +make HOST_CC="gcc -m32" CROSS=mipsel-linux- + +# MIPS64 big-endian +make CROSS=mips-linux- TARGET_CFLAGS="-mips64r2 -mabi=64" +# MIPS64 little-endian +make CROSS=mipsel-linux- TARGET_CFLAGS="-mips64r2 -mabi=64" +</pre> +<p> +You can cross-compile for <b id="android">Android</b> using the <a href="https://developer.android.com/ndk/"><span class="ext">»</span> Android NDK</a>. +Please adapt the environment variables to match the install locations and the +desired target platform. E.g. Android 4.1 corresponds to ABI level 16. +</p> +<pre class="code"> +# Android/ARM64, aarch64, Android 5.0+ (L) +NDKDIR=/opt/android/ndk +NDKBIN=$NDKDIR/toolchains/llvm/prebuilt/linux-x86_64/bin +NDKCROSS=$NDKBIN/aarch64-linux-android- +NDKCC=$NDKBIN/aarch64-linux-android21-clang +make CROSS=$NDKCROSS \ + STATIC_CC=$NDKCC DYNAMIC_CC="$NDKCC -fPIC" \ + TARGET_LD=$NDKCC TARGET_AR="$NDKBIN/llvm-ar rcus" \ + TARGET_STRIP=$NDKBIN/llvm-strip + +# Android/ARM, armeabi-v7a (ARMv7 VFP), Android 4.1+ (JB) +NDKDIR=/opt/android/ndk +NDKBIN=$NDKDIR/toolchains/llvm/prebuilt/linux-x86_64/bin +NDKCROSS=$NDKBIN/arm-linux-androideabi- +NDKCC=$NDKBIN/armv7a-linux-androideabi16-clang +make HOST_CC="gcc -m32" CROSS=$NDKCROSS \ + STATIC_CC=$NDKCC DYNAMIC_CC="$NDKCC -fPIC" \ + TARGET_LD=$NDKCC TARGET_AR="$NDKBIN/llvm-ar rcus" \ + TARGET_STRIP=$NDKBIN/llvm-strip +</pre> +<p> +You can cross-compile for <b id="ios">iOS 3.0+</b> (iPhone/iPad) using the <a href="https://developer.apple.com/ios/"><span class="ext">»</span> iOS SDK</a>: +</p> +<p style="font-size: 8pt;"> +Note: <b>the JIT compiler is disabled for iOS</b>, because regular iOS Apps +are not allowed to generate code at runtime. You'll only get the performance +of the LuaJIT interpreter on iOS. This is still faster than plain Lua, but +much slower than the JIT compiler. Please complain to Apple, not me. +Or use Android. :-p +</p> +<pre class="code"> +# iOS/ARM64 +ISDKP=$(xcrun --sdk iphoneos --show-sdk-path) +ICC=$(xcrun --sdk iphoneos --find clang) +ISDKF="-arch arm64 -isysroot $ISDKP" +make DEFAULT_CC=clang CROSS="$(dirname $ICC)/" \ + TARGET_FLAGS="$ISDKF" TARGET_SYS=iOS +</pre> + +<h3 id="consoles">Cross-compiling for consoles</h3> +<p> +Building LuaJIT for consoles requires both a supported host compiler +(x86 or x64) and a cross-compiler from the official console SDK. +</p> +<p> +Due to restrictions on consoles, the JIT compiler is disabled and only +the fast interpreter is built. This is still faster than plain Lua, +but much slower than the JIT compiler. The FFI is disabled, too, since +it's not very useful in such an environment. +</p> +<p> +The following commands build a static library <tt>libluajit.a</tt>, +which can be linked against your game, just like the Lua library. +</p> +<p> +To cross-compile for <b id="ps3">PS3</b> from a Linux host (requires +32 bit GCC, i.e. multilib Linux/x64) or a Windows host (requires +32 bit MinGW), run this command: +</p> +<pre class="code"> +make HOST_CC="gcc -m32" CROSS=ppu-lv2- +</pre> +<p> +To cross-compile for the other consoles from a Windows host, open a +"Native Tools Command Prompt for VS". You need to choose either the 32 +or the 64 bit version of the host compiler to match the target. +Then <tt>cd</tt> to the <tt>src</tt> directory below where you've +unpacked the sources and run the build command given in the table: +</p> +<table class="compat"> +<tr class="compathead"> +<td class="compatname">Console</td> +<td class="compatbits">Bits</td> +<td class="compatx">Build Command</td> +</tr> +<tr class="odd separate"> +<td class="compatname"><b id="ps4">PS4</b></td> +<td class="compatbits">64</td> +<td class="compatx"><tt>ps4build</tt></td> +</tr> +<tr class="even"> +<td class="compatname"><b id="ps5">PS5</b></td> +<td class="compatbits">64</td> +<td class="compatx"><tt>ps5build</tt></td> +</tr> +<tr class="odd"> +<td class="compatname"><b id="psvita">PS Vita</b></td> +<td class="compatbits">32</td> +<td class="compatx"><tt>psvitabuild</tt></td> +</tr> +<tr class="even"> +<td class="compatname"><b id="xbox360">Xbox 360</b></td> +<td class="compatbits">32</td> +<td class="compatx"><tt>xedkbuild</tt></td> +</tr> +<tr class="odd"> +<td class="compatname"><b id="xboxone">Xbox One</b></td> +<td class="compatbits">64</td> +<td class="compatx"><tt>xb1build</tt></td> +</tr> +<tr class="even"> +<td class="compatname"><b id="nx32">Nintendo Switch NX32</b></td> +<td class="compatbits">32</td> +<td class="compatx"><tt>nxbuild</tt></td> +</tr> +<tr class="odd"> +<td class="compatname"><b id="nx64">Nintendo Switch NX64</b></td> +<td class="compatbits">64</td> +<td class="compatx"><tt>nxbuild</tt></td> +</tr> +</table> +<p> +Please check out the comments in the corresponding <tt>*.bat</tt> +file for more options. +</p> + +<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: +</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> +</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">»</span> 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 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 +<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="https://bitop.luajit.org/"><span class="ext">»</span> 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 — +simply use whatever <tt>make install</tt> creates. There's a reason +for all the files <em>and</em> directories it creates. +</p> +<p> +The build system uses GNU make and auto-detects 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 paths needed to locate 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><tt>MULTILIB</tt> sets the architecture-specific library path component +for multilib systems. The default is <tt>lib</tt>.</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 +overridden, 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, +TARGET_FLAGS, 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> +The tl;dr version of the above: +</p> +<pre class="code"> +make amalg PREFIX=/usr && \ +make install PREFIX=/usr DESTDIR=/tmp/buildroot +</pre> +<p> +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> +<div id="foot"> +<hr class="hide"> +Copyright © 2005-2022 +<span class="noprint"> +· +<a href="contact.html">Contact</a> +</span> +</div> +</body> +</html> |