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.3+ or iOS 3.0+	Windows XP/Vista/7
x86 (32 bit)	GCC 4.x GCC 3.4	GCC 4.x GCC 3.4	GCC 4.x GCC 3.4	MSVC, MSVC/EE WinSDK MinGW, Cygwin
x64 (64 bit)	GCC 4.x		GCC 4.x	MSVC + SDK v7.0 WinSDK v7.0
ARMv5+ ARM9E+	GCC 4.2+	GCC 4.2+	GCC 4.2+
PPC	GCC 4.3+	GCC 4.3+
PPC/e500v2	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. -

- -

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.0-beta9.tar.gz
-cd LuaJIT-2.0.0-beta9

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 x86, x64 or PPC 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: MACOSX_DEPLOYMENT_TARGET is set to 10.4 -in src/Makefile. Change it, if you want to build on an older version. -

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

-Note: to avoid overwriting a previous version, the beta test releases -only install the LuaJIT executable under the versioned name (i.e. -luajit-2.0.0-beta9). You probably want to create a symlink -for convenience, with a command like this: -

-sudo ln -sf luajit-2.0.0-beta9 /usr/local/bin/luajit
-

- -

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

-The build system has limited support for cross-compilation. For details -check the comments in src/Makefile. Here are some popular examples: -

-You can cross-compile to a 32 bit binary on a multilib x64 OS by -installing the multilib development packages (e.g. libc6-dev-i386 -on Debian/Ubuntu) and running: -

-make CC="gcc -m32"
-

-You can cross-compile for a Windows target on Debian/Ubuntu by -installing the mingw32 package and running: -

-make HOST_CC="gcc -m32" CROSS=i586-mingw32msvc- TARGET_SYS=Windows
-

-You can cross-compile for an ARM target on an x86 or x64 host -system using a standard GNU cross-compile toolchain (Binutils, GCC, -EGLIBC). The CROSS prefix may vary depending on the ---target of the toolchain: -

-make HOST_CC="gcc -m32" CROSS=arm-linux-gnueabi-
-

-You can cross-compile for Android (ARM) using the » Android NDK. -The environment variables need to match the install locations and the -desired target platform. E.g. Android 2.2 corresponds to ABI level 8: -

-NDK=/opt/android/ndk
-NDKABI=8
-NDKVER=$NDK/toolchains/arm-linux-androideabi-4.4.3
-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"
-

-You can cross-compile for iOS 3.0+ (iPhone/iPad) using the » iOS SDK. -The environment variables need to match the iOS SDK version: -

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

-ISDK=/Developer/Platforms/iPhoneOS.platform/Developer
-ISDKVER=iPhoneOS4.3.sdk
-ISDKP=$ISDK/usr/bin/
-ISDKF="-arch armv6 -isysroot $ISDK/SDKs/$ISDKVER"
-make HOST_CC="gcc -m32 -arch i386" CROSS=$ISDKP TARGET_FLAGS="$ISDKF" \
-     TARGET_SYS=iOS
-

-You can cross-compile for a PPC target or a -PPC/e500v2 target on x86 or x64 host systems using a standard -GNU cross-compile toolchain (Binutils, GCC, EGLIBC). -The CROSS prefix may vary depending on the --target -of the toolchain: -

-# PPC
-make HOST_CC="gcc -m32" CROSS=powerpc-linux-gnu-
-

-# PPC/e500v2
-make HOST_CC="gcc -m32" CROSS=powerpc-e500v2-linux-gnuspe-
-

-Whenever the host OS and the target OS differ, you need to specify -TARGET_SYS 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 above. For a -minimal target OS, you may need to disable the built-in allocator in -src/Makefile and use TARGET_SYS=Other. -

- -

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

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

-
-