Installation

+LuaJIT is only distributed as a source package. This page explains +how to build and install LuaJIT with different operating systems +and C compilers. +

+For the impatient (on POSIX systems): +

+make && sudo make install
+

+LuaJIT currently builds out-of-the box on most systems. +Here's the compatibility matrix for the supported combinations of +operating systems, CPUs and compilers: +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

CPU / OS	Linux or Android	*BSD, Other	OSX 10.4+ or iOS 3.0+	Windows XP/Vista/7
x86 (32 bit)	GCC 4.2+	GCC 4.2+	XCode 5.0+ Clang	MSVC, MSVC/EE WinSDK MinGW, Cygwin
x64 (64 bit)	GCC 4.2+	GCC 4.2+ ORBIS (PS4)	XCode 5.0+ Clang	MSVC + SDK v7.0 WinSDK v7.0 Durango (Xbox One)
ARMv5+ ARM9E+	GCC 4.2+	GCC 4.2+ PSP2 (PS VITA)	XCode 5.0+ Clang
ARM64	GCC 4.8+		XCode 6.0+ Clang 3.5+
PPC	GCC 4.3+	GCC 4.3+ GCC 4.1 (PS3)		XEDK (Xbox 360)
MIPS32 MIPS64	GCC 4.3+	GCC 4.3+

+ +

Configuring LuaJIT

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

src/luaconf.h sets some configuration variables.
Makefile has settings for installing LuaJIT (POSIX +only).
src/Makefile has settings for compiling LuaJIT +under POSIX, MinGW or Cygwin.
src/msvcbuild.bat has settings for compiling LuaJIT with +MSVC or WinSDK.

+Please read the instructions given in these files, before changing +any settings. +

+LuaJIT on x64 currently uses 32 bit GC objects by default. +LJ_GC64 mode may be explicitly enabled: +add XCFLAGS=-DLUAJIT_ENABLE_GC64 to the make command or run +msvcbuild gc64 for MSVC/WinSDK. Please check the note +about the bytecode format +differences, too. +

+ +

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

Prerequisites

+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 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, +open a terminal window and change to this directory. Now unpack the archive +and change to the newly created directory: +

+tar zxf LuaJIT-2.0.5.tar.gz
+cd LuaJIT-2.0.5

Building LuaJIT

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

+make
+

+This always builds a native binary, depending on the host OS +you're running this command on. Check the section on +cross-compilation for more options. +

+By default, modules are only searched under the prefix /usr/local. +You can add an extra prefix to the search paths by appending the +PREFIX option, e.g.: +

+make PREFIX=/home/myself/lj2
+

+Note for OSX: if the MACOSX_DEPLOYMENT_TARGET environment +variable is not set, then it's forced to 10.4. +

Installing LuaJIT

+The top-level Makefile installs LuaJIT by default under +/usr/local, i.e. the executable ends up in +/usr/local/bin 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: +

+sudo make install
+

+Otherwise specify the directory prefix as an absolute path, e.g.: +

+make install PREFIX=/home/myself/lj2
+

+Obviously the prefixes given during build and installation need to be the same. +

+ +

Windows Systems

Prerequisites

+Either install one of the open source SDKs +(» MinGW or +» Cygwin), which come with a modified +GCC plus the required development headers. +

+Or install Microsoft's Visual C++ (MSVC). The freely downloadable +» Express Edition +works just fine, but only contains an x86 compiler. +

+The freely downloadable +» Windows SDK +only comes with command line tools, but this is all you need to build LuaJIT. +It contains x86 and x64 compilers. +

+Next, 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

+Open a "Visual Studio .NET Command Prompt", cd to the +directory where you've unpacked the sources and run these commands: +

+cd src
+msvcbuild
+

+Then follow the installation instructions below. +

Building with the Windows SDK

+Open a "Windows SDK Command Shell" and select the x86 compiler: +

+setenv /release /x86
+

+Or select the x64 compiler: +

+setenv /release /x64
+

+Then cd to the directory where you've unpacked the sources +and run these commands: +

+cd src
+msvcbuild
+

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

+mingw32-make
+

+Or this command for Cygwin: +

+make
+

+Then follow the installation instructions below. +

Installing LuaJIT

+Copy luajit.exe and lua51.dll (built in the src +directory) to a newly created directory (any location is ok). +Add lua and lua\jit directories below it and copy +all Lua files from the src\jit directory of the distribution +to the latter directory. +

+There are no hardcoded +absolute path names — all modules are loaded relative to the +directory where luajit.exe is installed +(see src/luaconf.h). +

+ +

Cross-compiling LuaJIT

+First, let's clear up some terminology: +

Host: This is your development system, usually based on a x64 or x86 CPU.
Target: This is the target system you want LuaJIT to run on, e.g. Android/ARM.
Toolchain: This comprises a C compiler, linker, assembler and a matching C library.
Host (or system) toolchain: This is the toolchain used to build native binaries for your host system.
Cross-compile toolchain: This is the toolchain used to build binaries for the target system. They can only be run on the target system.

+The GNU Makefile-based build system allows cross-compiling on any host +for any supported target: +

Yes, you need a toolchain for both your host and your target!
Both host and target architectures must have the same pointer size.
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. libc6-dev-i386 on Debian/Ubuntu) and build a 32 bit host part (HOST_CC="gcc -m32").
64 bit targets always require compilation on a 64 bit host.

+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 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 specify the same TARGET_SYS for the install step, too.

+Here are some examples where host and target have the same CPU: +

+# 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
+

+The CROSS prefix allows specifying a standard GNU cross-compile +toolchain (Binutils, GCC and a matching libc). The prefix may vary +depending on the --target the toolchain was built for (note the +CROSS prefix has a trailing "-"). The examples below +use the canonical toolchain triplets for Linux. +

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

The best way to get consistent results is to specify the correct settings when building the toolchain yourself.
For a pre-built, generic toolchain add -mcpu=... or -march=... and other necessary flags to TARGET_CFLAGS.
For ARM it's important to have the correct -mfloat-abi=... setting, too. Otherwise LuaJIT may not run at the full performance of your target CPU.
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.

+Here are some examples for targets with a different CPU than the host: +

+# 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"
+

+You can cross-compile for Android using the Android NDK. +The environment variables need to match the install locations and the +desired target platform. E.g. Android 4.0 corresponds to ABI level 14. +For details check the folder docs in the NDK directory. +

+Only a few common variations for the different CPUs, ABIs and platforms +are listed. Please use your own judgement for which combination you want +to build/deploy or which lowest common denominator you want to pick: +

+# Android/ARM, armeabi (ARMv5TE soft-float), Android 2.2+ (Froyo)
+NDK=/opt/android/ndk
+NDKABI=8
+NDKVER=$NDK/toolchains/arm-linux-androideabi-4.9
+NDKP=$NDKVER/prebuilt/linux-x86/bin/arm-linux-androideabi-
+NDKF="--sysroot $NDK/platforms/android-$NDKABI/arch-arm"
+make HOST_CC="gcc -m32" CROSS=$NDKP TARGET_FLAGS="$NDKF"
+
+# Android/ARM, armeabi-v7a (ARMv7 VFP), Android 4.0+ (ICS)
+NDK=/opt/android/ndk
+NDKABI=14
+NDKVER=$NDK/toolchains/arm-linux-androideabi-4.9
+NDKP=$NDKVER/prebuilt/linux-x86/bin/arm-linux-androideabi-
+NDKF="--sysroot $NDK/platforms/android-$NDKABI/arch-arm"
+NDKARCH="-march=armv7-a -mfloat-abi=softfp -Wl,--fix-cortex-a8"
+make HOST_CC="gcc -m32" CROSS=$NDKP TARGET_FLAGS="$NDKF $NDKARCH"
+
+# Android/MIPS, mipsel (MIPS32R1 hard-float), Android 4.0+ (ICS)
+NDK=/opt/android/ndk
+NDKABI=14
+NDKVER=$NDK/toolchains/mipsel-linux-android-4.9
+NDKP=$NDKVER/prebuilt/linux-x86/bin/mipsel-linux-android-
+NDKF="--sysroot $NDK/platforms/android-$NDKABI/arch-mips"
+make HOST_CC="gcc -m32" CROSS=$NDKP TARGET_FLAGS="$NDKF"
+
+# Android/x86, x86 (i686 SSE3), Android 4.0+ (ICS)
+NDK=/opt/android/ndk
+NDKABI=14
+NDKVER=$NDK/toolchains/x86-4.9
+NDKP=$NDKVER/prebuilt/linux-x86/bin/i686-linux-android-
+NDKF="--sysroot $NDK/platforms/android-$NDKABI/arch-x86"
+make HOST_CC="gcc -m32" CROSS=$NDKP TARGET_FLAGS="$NDKF"
+

+You can cross-compile for iOS 3.0+ (iPhone/iPad) using the » iOS SDK: +

+Note: the JIT compiler is disabled for iOS, 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 +

+# iOS/ARM (32 bit)
+ISDKP=$(xcrun --sdk iphoneos --show-sdk-path)
+ICC=$(xcrun --sdk iphoneos --find clang)
+ISDKF="-arch armv7 -isysroot $ISDKP"
+make DEFAULT_CC=clang HOST_CC="clang -m32 -arch i386" \
+     CROSS="$(dirname $ICC)/" TARGET_FLAGS="$ISDKF" TARGET_SYS=iOS
+
+# 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
+

+ +

Cross-compiling for consoles

+Building LuaJIT for consoles requires both a supported host compiler +(x86 or x64) and a cross-compiler (to PPC or ARM) from the official +console SDK. +

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

+The following commands build a static library libluajit.a, +which can be linked against your game, just like the Lua library. +

+To cross-compile for PS3 from a Linux host (requires +32 bit GCC, i.e. multilib Linux/x64) or a Windows host (requires +32 bit MinGW), run this command: +

+make HOST_CC="gcc -m32" CROSS=ppu-lv2-
+

+To cross-compile for PS4 from a Windows host, +open a "Visual Studio .NET Command Prompt" (64 bit host compiler), +cd to the directory where you've unpacked the sources and +run the following commands: +

+cd src
+ps4build
+

+To cross-compile for PS Vita from a Windows host, +open a "Visual Studio .NET Command Prompt" (32 bit host compiler), +cd to the directory where you've unpacked the sources and +run the following commands: +

+cd src
+psvitabuild
+

+To cross-compile for Xbox 360 from a Windows host, +open a "Visual Studio .NET Command Prompt" (32 bit host compiler), +cd to the directory where you've unpacked the sources and run +the following commands: +

+cd src
+xedkbuild
+

+To cross-compile for Xbox One from a Windows host, +open a "Visual Studio .NET Command Prompt" (64 bit host compiler), +cd to the directory where you've unpacked the sources and run +the following commands: +

+cd src
+xb1build
+

+ +

Embedding LuaJIT

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

It's strongly suggested to build LuaJIT separately using the supplied +build system. Please do not 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.
If you want to load C modules compiled for plain Lua +with require(), you need to make sure the public symbols +(e.g. lua_pushnumber) are exported, too: +
- 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. -Wl,-E on Linux) and add the external dependencies +(e.g. -lm -ldl on Linux).
- Since Windows symbols are bound to a specific DLL name, you need to +link to the lua51.dll 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. +
+
+If you're building a 64 bit application on OSX which links directly or +indirectly against LuaJIT which is not built for LJ_GC64 mode, +you need to link your main executable with these flags: +
```
+-pagezero_size 10000 -image_base 100000000
+
```
+

Additional hints for initializing LuaJIT using the C API functions:

Here's a +» simple example +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).
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 +src/lib_init.c to your project and modify it accordingly. +Make sure the jit library is loaded or the JIT compiler +will not be activated.
The bit.* module for bitwise operations +is already built-in. There's no need to statically link +» Lua BitOp to your application.

+ +

Hints for Distribution Maintainers

+The LuaJIT build system has extra provisions for the needs of most +POSIX-based distributions. If you're a package maintainer for +a distribution, please make use of these features and +avoid patching, subverting, autotoolizing or messing up the build system +in unspeakable ways. +

+There should be absolutely no need to patch luaconf.h or any +of the Makefiles. And please do not hand-pick files for your packages — +simply use whatever make install creates. There's a reason +for all of the files and directories it creates. +

+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 +both the make and the make install command lines +for a regular distribution build: +

PREFIX overrides the installation path and should usually +be set to /usr. Setting this also changes the module paths and +the paths needed to locate the shared library.
DESTDIR is an absolute path which allows you to install +to a shadow tree instead of the root tree of the build system.
MULTILIB sets the architecture-specific library path component +for multilib systems. The default is lib.
Have a look at the top-level Makefile and src/Makefile +for additional variables to tweak. The following variables may be +overridden, but it's not recommended, except for special needs +like cross-builds: +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 +

+The build system has a special target for an amalgamated build, i.e. +make amalg. 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. +

+The tl;dr version of the above: +

+make amalg PREFIX=/usr && \
+make install PREFIX=/usr DESTDIR=/tmp/buildroot
+

+Finally, if you encounter any difficulties, please +contact me 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. +

+
+