Installing LuaJIT

LuaJIT is not much more difficult to install than Lua itself. Just unpack the distribution file, change into the newly created directory and follow the instructions below.

For the impatient: make linux && sudo make install
Replace linux with e.g. bsd or macosx depending on your OS.

In case you've missed this in Features: LuaJIT only works on x86 (i386+) systems right now. Support for other architectures may be added in future versions.

Configuring LuaJIT

LuaJIT is (deliberately) not autoconfigured — the defaults should work fine on most systems. But please check the system-specific instructions below.

The following three files hold all configuration information:

Makefile holds settings for installing LuaJIT.
src/Makefile holds settings for compiling LuaJIT.
src/luaconf.h sets a multitude of configuration variables.

If this is your first build then it's better not to give into the temptation to tweak every little setting. The standard configuration provides sensible defaults (IMHO).

One particular setting you might want to change is the installation path. Note that you need to modify both the top-level Makefile and src/luaconf.h (right at the start) to take effect.

If you have trouble getting Coco to work, you can disable it by uncommenting the COCOFLAGS= -DCOCO_DISABLE line in src/Makefile. But note that this effectively disables yielding from coroutines for JIT compiled functions.

A few more settings need to be changed if you want to Debug LuaJIT itself. Application debugging can be turned on/off at runtime.

Upgrading From Previous Versions

It's important to keep the LuaJIT core and the add-on modules in sync. Be sure to delete any old versions of LuaJIT modules from the Lua module search path (check the current directory, too!).

Lua files compiled to bytecode may be incompatible if the underlying Lua core has changed (like from Lua 5.1 alpha to Lua 5.1 final between LuaJIT 1.0.3 and LuaJIT 1.1.0). The same applies to any » loadable C modules (shared libraries, DLLs) which need to be recompiled with the new Lua header files.

Compiled bytecode and loadable C modules are fully compatible and can be freely exchanged between LuaJIT and the same version of Lua it is based on. Please verify that LUA_RELEASE in src/lua.h is the same in both distributions.

Building LuaJIT

Makefile Targets

The Makefiles have a number of targets for various operating systems:

System	Build Command	Notes
Linux i386	make linux
BSD i386	make bsd	FreeBSD, NetBSD or OpenBSD
Mac OS X on Intel	make macosx	Check `src/Makefile` for OS X < 10.4
Solaris x86	make solaris	GCC only, SunCC miscompiles LuaJIT
MinGW (Win32)	make mingw	cross-MinGW: must be 1st in PATH
Cygwin	make cygwin
POSIX on x86	make posix	Check Portability Req. for Coco, too
Generic x86	make generic	Check Portability Req. for Coco, too

You may want to enable interactive line editing for the stand-alone executable. There are extra targets for Linux, BSD and Mac OS X: make linux_rl, make bsd_rl and make macosx_rl.

MSVC (Win32)

First check out etc\luavs.bat if it suits your needs. Then try running it from the MSVC command prompt (start it from the toplevel directory).

Another option is to set up your own MSVC project:

Change to the src directory and create a new DLL project for lua51.dll. Add all C files to it except for lua.c, luac.c and print.c. Add the ..\dynasm directory to the include path and build the DLL.

Next create a new EXE project for luajit.exe. Add lua.c to it and link with the import library lua51.lib created for lua51.dll. Build the executable.

Installation

POSIX systems

Run make install from the top-level directory. You probably need to be the root user before doing so, i.e. use sudo make install or su - root before the make install.

By default this installs only:
  /usr/local/bin/luajit — The stand-alone executable.
  /usr/local/lib/lua/5.1 — C module directory.
  /usr/local/share/lua/5.1 — Lua module directory.
  /usr/local/share/lua/5.1/jit/*.lua — jit.* modules.

The Lua docs and includes are not installed to avoid overwriting an existing Lua installation. In any case these are identical to the version of Lua that LuaJIT is based on. If you want to install them, edit the top-level makefile (look for ###).

The stand-alone Lua bytecode compiler luac is neither built nor installed, for the same reason. If you really need it, you may be better off with luac built from the original Lua distribution (use the same version your copy of LuaJIT is based on). This avoids dragging in most of LuaJIT which is not needed for the pure bytecode compiler. You can also use the bare-bones Lua to bytecode translator luac.lua (look in the test directory of the original Lua distribution).

Windows

Copy luajit.exe and lua51.dll to a newly created directory (any location is ok). Add lua and lua\jit directories below it and copy all Lua files from the 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).

Embedding LuaJIT

It's strongly recommended that you build the stand-alone executable with your toolchain and verify that it works before starting to embed LuaJIT into an application. The stand-alone executable is also useful later on, when you want to experiment with code snippets or try out some Lua files.

Please consult the Lua docs for general information about how to embed Lua into your application. The following list only shows the additional steps needed for embedding LuaJIT:

You need to add the LuaJIT library functions by running luaopen_jit() after all the other standard library functions. The modified src/linit.c used by the stand-alone executable already does this for you.
Caveat: LuaJIT is based on Lua 5.1 which means the luaopen_*() functions must not be called directly. See src/linit.c for the proper way to run them. You'll get an error initializing the io library if you don't follow these instructions.
To use the optimizer (strongly recommended) you need to:
- Install the optimizer modules jit.opt and jit.opt_inline relative to the Lua module path (you've probably modified it — see src/luaconf.h):
  jit/opt.lua
  jit/opt_inline.lua
- If you want to ship a single executable then you may want to embed the optimizer modules into your application (but don't loose time with this during the early development phase). This involves:
  - Compile the two modules to bytecode (using luac -s from a plain Lua installation).
  - Convert them to C include files (search for "Lua bin2c").
  - On Windows you can also put the compiled bytecode into a resource (search for "Lua bin2res").
  - Load the bytecode with luaL_loadbuffer (but don't run it).
  - Put the resulting functions into package.preload["jit.opt"] and package.preload["jit.opt_inline"].
- Activate the LuaJIT optimizer from Lua code to be run at startup: require("jit.opt").start()
  Or use equivalent C code. See dojitopt() in src/lua.c.
All other LuaJIT specific modules (jit.*) are for debugging only. They do not need to be shipped with an application. But they may be quite useful, anyway (especially jit.trace).
DynASM is only needed while building LuaJIT. It's not needed while running LuaJIT and there is no point in shipping or installing it together with an application.
In case you want to strip some of the standard libraries from your application: The optimizer modules need several functions from the base library and the string library (and of course the LuaJIT core libraries). The io library is only used to print a fatal error message (you may want to replace it). The optional modules for debugging depend on a few more library functions — please check the source.

Although the very liberal LuaJIT » license does not require any acknowledgment whatsoever, it would be appreciated if you give some credit in the docs (or the "About" box) of your application. A simple line like:
This product includes LuaJIT, http://luajit.org/
would be nice. Please do not include any E-Mail addresses. Thank you!

I'm always interested where LuaJIT can be put to good use in applications. Please tell me or better yet write a few lines about your project to the » Lua mailing list. Thank you!