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