RELEASE LuaJIT-2.0.0-beta9
[luajit-2.0.git] / doc / install.html
blob4e226d173f0c33702100608d3840b08af18cbcce
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
2 <html>
3 <head>
4 <title>Installation</title>
5 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
6 <meta name="Author" content="Mike Pall">
7 <meta name="Copyright" content="Copyright (C) 2005-2011, Mike Pall">
8 <meta name="Language" content="en">
9 <link rel="stylesheet" type="text/css" href="bluequad.css" media="screen">
10 <link rel="stylesheet" type="text/css" href="bluequad-print.css" media="print">
11 <style type="text/css">
12 table.compat {
13 line-height: 1.2;
14 width: 600px;
16 table.compat td {
17 border: 1px solid #bfcfff;
18 font-size: 90%;
19 height: 2.5em;
21 table.compat tr.compathead td {
22 font-weight: bold;
23 border-bottom: 2px solid #bfcfff;
25 tr.compathead td.compatos {
26 vertical-align: top;
28 table.compat td.compatcpu {
29 width: 16%;
30 border-right: 2px solid #bfcfff;
32 td.compatos {
33 width: 21%;
34 vertical-align: middle;
36 td.compatno {
37 background-color: #d0d0d0;
39 </style>
40 </head>
41 <body>
42 <div id="site">
43 <a href="http://luajit.org"><span>Lua<span id="logo">JIT</span></span></a>
44 </div>
45 <div id="head">
46 <h1>Installation</h1>
47 </div>
48 <div id="nav">
49 <ul><li>
50 <a href="luajit.html">LuaJIT</a>
51 <ul><li>
52 <a class="current" href="install.html">Installation</a>
53 </li><li>
54 <a href="running.html">Running</a>
55 </li></ul>
56 </li><li>
57 <a href="extensions.html">Extensions</a>
58 <ul><li>
59 <a href="ext_ffi.html">FFI Library</a>
60 <ul><li>
61 <a href="ext_ffi_tutorial.html">FFI Tutorial</a>
62 </li><li>
63 <a href="ext_ffi_api.html">ffi.* API</a>
64 </li><li>
65 <a href="ext_ffi_semantics.html">FFI Semantics</a>
66 </li></ul>
67 </li><li>
68 <a href="ext_jit.html">jit.* Library</a>
69 </li><li>
70 <a href="ext_c_api.html">Lua/C API</a>
71 </li></ul>
72 </li><li>
73 <a href="status.html">Status</a>
74 <ul><li>
75 <a href="changes.html">Changes</a>
76 </li></ul>
77 </li><li>
78 <a href="faq.html">FAQ</a>
79 </li><li>
80 <a href="http://luajit.org/performance.html">Performance <span class="ext">&raquo;</span></a>
81 </li><li>
82 <a href="http://luajit.org/download.html">Download <span class="ext">&raquo;</span></a>
83 </li></ul>
84 </div>
85 <div id="main">
86 <p>
87 LuaJIT is only distributed as a source package. This page explains
88 how to build and install LuaJIT with different operating systems
89 and C&nbsp;compilers.
90 </p>
91 <p>
92 For the impatient (on POSIX systems):
93 </p>
94 <pre class="code">
95 make &amp;&amp; sudo make install
96 </pre>
97 <p>
98 LuaJIT currently builds out-of-the box on most systems.
99 Here's the compatibility matrix for the supported combinations of
100 operating systems, CPUs and compilers:
101 </p>
102 <table class="compat">
103 <tr class="compathead">
104 <td class="compatcpu">CPU / OS</td>
105 <td class="compatos"><a href="#posix">Linux</a> or<br><a href="#android">Android</a></td>
106 <td class="compatos"><a href="#posix">*BSD, Other</a></td>
107 <td class="compatos"><a href="#posix">OSX 10.3+</a> or<br><a href="#ios">iOS 3.0+</a></td>
108 <td class="compatos"><a href="#windows">Windows<br>XP/Vista/7</a></td>
109 </tr>
110 <tr class="odd separate">
111 <td class="compatcpu">x86 (32 bit)</td>
112 <td class="compatos">GCC 4.x<br>GCC 3.4</td>
113 <td class="compatos">GCC 4.x<br>GCC 3.4</td>
114 <td class="compatos">GCC 4.x<br>GCC 3.4</td>
115 <td class="compatos">MSVC, MSVC/EE<br>WinSDK<br>MinGW, Cygwin</td>
116 </tr>
117 <tr class="even">
118 <td class="compatcpu">x64 (64 bit)</td>
119 <td class="compatos">GCC 4.x</td>
120 <td class="compatos compatno">&nbsp;</td>
121 <td class="compatos">GCC 4.x</td>
122 <td class="compatos">MSVC + SDK v7.0<br>WinSDK v7.0</td>
123 </tr>
124 <tr class="odd">
125 <td class="compatcpu"><a href="#android">ARMv5+<br>ARM9E+</a></td>
126 <td class="compatos">GCC 4.2+</td>
127 <td class="compatos">GCC 4.2+</td>
128 <td class="compatos">GCC 4.2+</td>
129 <td class="compatos compatno">&nbsp;</td>
130 </tr>
131 <tr class="even">
132 <td class="compatcpu"><a href="#ppc">PPC</a></td>
133 <td class="compatos">GCC 4.3+</td>
134 <td class="compatos">GCC 4.3+</td>
135 <td class="compatos compatno">&nbsp;</td>
136 <td class="compatos compatno">&nbsp;</td>
137 </tr>
138 <tr class="odd">
139 <td class="compatcpu"><a href="#ppc">PPC/e500v2</a></td>
140 <td class="compatos">GCC 4.3+</td>
141 <td class="compatos">GCC 4.3+</td>
142 <td class="compatos compatno">&nbsp;</td>
143 <td class="compatos compatno">&nbsp;</td>
144 </tr>
145 </table>
147 <h2>Configuring LuaJIT</h2>
149 The standard configuration should work fine for most installations.
150 Usually there is no need to tweak the settings. The following files
151 hold all user-configurable settings:
152 </p>
153 <ul>
154 <li><tt>src/luaconf.h</tt> sets some configuration variables.</li>
155 <li><tt>Makefile</tt> has settings for <b>installing</b> LuaJIT (POSIX
156 only).</li>
157 <li><tt>src/Makefile</tt> has settings for <b>compiling</b> LuaJIT
158 under POSIX, MinGW or Cygwin.</li>
159 <li><tt>src/msvcbuild.bat</tt> has settings for compiling LuaJIT with
160 MSVC or WinSDK.</li>
161 </ul>
163 Please read the instructions given in these files, before changing
164 any settings.
165 </p>
167 <h2 id="posix">POSIX Systems (Linux, OSX, *BSD etc.)</h2>
168 <h3>Prerequisites</h3>
170 Depending on your distribution, you may need to install a package for
171 GCC, the development headers and/or a complete SDK. E.g. on a current
172 Debian/Ubuntu, install <tt>libc6-dev</tt> with the package manager.
173 </p>
175 Download the current source package of LuaJIT (pick the .tar.gz),
176 if you haven't already done so. Move it to a directory of your choice,
177 open a terminal window and change to this directory. Now unpack the archive
178 and change to the newly created directory:
179 </p>
180 <pre class="code">
181 tar zxf LuaJIT-2.0.0-beta9.tar.gz
182 cd LuaJIT-2.0.0-beta9</pre>
183 <h3>Building LuaJIT</h3>
185 The supplied Makefiles try to auto-detect the settings needed for your
186 operating system and your compiler. They need to be run with GNU Make,
187 which is probably the default on your system, anyway. Simply run:
188 </p>
189 <pre class="code">
190 make
191 </pre>
193 This always builds a native x86, x64 or PPC binary, depending on the host OS
194 you're running this command on. Check the section on
195 <a href="#cross">cross-compilation</a> for more options.
196 </p>
198 By default, modules are only searched under the prefix <tt>/usr/local</tt>.
199 You can add an extra prefix to the search paths by appending the
200 <tt>PREFIX</tt> option, e.g.:
201 </p>
202 <pre class="code">
203 make PREFIX=/home/myself/lj2
204 </pre>
206 Note for OSX: <tt>MACOSX_DEPLOYMENT_TARGET</tt> is set to <tt>10.4</tt>
207 in <tt>src/Makefile</tt>. Change it, if you want to build on an older version.
208 </p>
209 <h3>Installing LuaJIT</h3>
211 The top-level Makefile installs LuaJIT by default under
212 <tt>/usr/local</tt>, i.e. the executable ends up in
213 <tt>/usr/local/bin</tt> and so on. You need root privileges
214 to write to this path. So, assuming sudo is installed on your system,
215 run the following command and enter your sudo password:
216 </p>
217 <pre class="code">
218 sudo make install
219 </pre>
221 Otherwise specify the directory prefix as an absolute path, e.g.:
222 </p>
223 <pre class="code">
224 make install PREFIX=/home/myself/lj2
225 </pre>
227 Obviously the prefixes given during build and installation need to be the same.
228 </p>
229 <p style="color: #c00000;">
230 Note: to avoid overwriting a previous version, the beta test releases
231 only install the LuaJIT executable under the versioned name (i.e.
232 <tt>luajit-2.0.0-beta9</tt>). You probably want to create a symlink
233 for convenience, with a command like this:
234 </p>
235 <pre class="code" style="color: #c00000;">
236 sudo ln -sf luajit-2.0.0-beta9&nbsp;/usr/local/bin/luajit
237 </pre>
239 <h2 id="windows">Windows Systems</h2>
240 <h3>Prerequisites</h3>
242 Either install one of the open source SDKs
243 (<a href="http://mingw.org/"><span class="ext">&raquo;</span>&nbsp;MinGW</a> or
244 <a href="http://www.cygwin.com/"><span class="ext">&raquo;</span>&nbsp;Cygwin</a>), which come with a modified
245 GCC plus the required development headers.
246 </p>
248 Or install Microsoft's Visual C++ (MSVC). The freely downloadable
249 <a href="http://www.microsoft.com/Express/VC/"><span class="ext">&raquo;</span>&nbsp;Express Edition</a>
250 works just fine, but only contains an x86 compiler.
251 </p>
253 The freely downloadable
254 <a href="http://msdn.microsoft.com/en-us/windowsserver/bb980924.aspx"><span class="ext">&raquo;</span>&nbsp;Windows SDK</a>
255 only comes with command line tools, but this is all you need to build LuaJIT.
256 It contains x86 and x64 compilers.
257 </p>
259 Next, download the source package and unpack it using an archive manager
260 (e.g. the Windows Explorer) to a directory of your choice.
261 </p>
262 <h3>Building with MSVC</h3>
264 Open a "Visual Studio .NET Command Prompt", <tt>cd</tt> to the
265 directory where you've unpacked the sources and run these commands:
266 </p>
267 <pre class="code">
268 cd src
269 msvcbuild
270 </pre>
272 Then follow the installation instructions below.
273 </p>
274 <h3>Building with the Windows SDK</h3>
276 Open a "Windows SDK Command Shell" and select the x86 compiler:
277 </p>
278 <pre class="code">
279 setenv /release /x86
280 </pre>
282 Or select the x64 compiler:
283 </p>
284 <pre class="code">
285 setenv /release /x64
286 </pre>
288 Then <tt>cd</tt> to the directory where you've unpacked the sources
289 and run these commands:
290 </p>
291 <pre class="code">
292 cd src
293 msvcbuild
294 </pre>
296 Then follow the installation instructions below.
297 </p>
298 <h3>Building with MinGW or Cygwin</h3>
300 Open a command prompt window and make sure the MinGW or Cygwin programs
301 are in your path. Then <tt>cd</tt> to the directory where
302 you've unpacked the sources and run this command for MinGW:
303 </p>
304 <pre class="code">
305 mingw32-make
306 </pre>
308 Or this command for Cygwin:
309 </p>
310 <pre class="code">
311 make
312 </pre>
314 Then follow the installation instructions below.
315 </p>
316 <h3>Installing LuaJIT</h3>
318 Copy <tt>luajit.exe</tt> and <tt>lua51.dll</tt> (built in the <tt>src</tt>
319 directory) to a newly created directory (any location is ok).
320 Add <tt>lua</tt> and <tt>lua\jit</tt> directories below it and copy
321 all Lua files from the <tt>lib</tt> directory of the distribution
322 to the latter directory.
323 </p>
325 There are no hardcoded
326 absolute path names &mdash; all modules are loaded relative to the
327 directory where <tt>luajit.exe</tt> is installed
328 (see <tt>src/luaconf.h</tt>).
329 </p>
331 <h2 id="cross">Cross-compiling LuaJIT</h2>
333 The build system has limited support for cross-compilation. For details
334 check the comments in <tt>src/Makefile</tt>. Here are some popular examples:
335 </p>
337 You can cross-compile to a <b>32 bit binary on a multilib x64 OS</b> by
338 installing the multilib development packages (e.g. <tt>libc6-dev-i386</tt>
339 on Debian/Ubuntu) and running:
340 </p>
341 <pre class="code">
342 make CC="gcc -m32"
343 </pre>
345 You can cross-compile for a <b>Windows target on Debian/Ubuntu</b> by
346 installing the <tt>mingw32</tt> package and running:
347 </p>
348 <pre class="code">
349 make HOST_CC="gcc -m32" CROSS=i586-mingw32msvc- TARGET_SYS=Windows
350 </pre>
352 You can cross-compile for an <b>ARM target</b> on an x86 or x64 host
353 system using a standard GNU cross-compile toolchain (Binutils, GCC,
354 EGLIBC). The <tt>CROSS</tt> prefix may vary depending on the
355 <tt>--target</tt> of the toolchain:
356 </p>
357 <pre class="code">
358 make HOST_CC="gcc -m32" CROSS=arm-linux-gnueabi- TARGET=arm
359 </pre>
361 You can cross-compile for <b id="android">Android (ARM)</b> using the <a href="http://developer.android.com/sdk/ndk/index.html"><span class="ext">&raquo;</span>&nbsp;Android NDK</a>.
362 The environment variables need to match the install locations and the
363 desired target platform. E.g. Android&nbsp;2.2 corresponds to ABI level&nbsp;8:
364 </p>
365 <pre class="code">
366 NDK=/opt/android/ndk
367 NDKABI=8
368 NDKVER=$NDK/toolchains/arm-linux-androideabi-4.4.3
369 NDKP=$NDKVER/prebuilt/linux-x86/bin/arm-linux-androideabi-
370 NDKF="--sysroot $NDK/platforms/android-$NDKABI/arch-arm"
371 make HOST_CC="gcc -m32" CROSS=$NDKP TARGET_FLAGS="$NDKF" TARGET=arm
372 </pre>
374 You can cross-compile for <b id="ios">iOS 3.0+</b> (iPhone/iPad) using the <a href="http://developer.apple.com/devcenter/ios/index.action"><span class="ext">&raquo;</span>&nbsp;iOS SDK</a>.
375 The environment variables need to match the iOS SDK version:
376 </p>
377 <p style="font-size: 8pt;">
378 Note: <b>the JIT compiler is disabled for iOS</b>, because regular iOS Apps
379 are not allowed to generate code at runtime. You'll only get the performance
380 of the LuaJIT interpreter on iOS. This is still faster than plain Lua, but
381 much slower than the JIT compiler. Please complain to Apple, not me.
382 Or use Android. :-p
383 </p>
384 <pre class="code">
385 ISDK=/Developer/Platforms/iPhoneOS.platform/Developer
386 ISDKVER=iPhoneOS4.3.sdk
387 ISDKP=$ISDK/usr/bin/
388 ISDKF="-arch armv6 -isysroot $ISDK/SDKs/$ISDKVER"
389 make HOST_CC="gcc -m32 -arch i386" CROSS=$ISDKP TARGET_FLAGS="$ISDKF" \
390 TARGET=arm TARGET_SYS=iOS
391 </pre>
393 You can cross-compile for a <b id="ppc">PPC target</b> or a
394 <b>PPC/e500v2 target</b> on x86 or x64 host systems using a standard
395 GNU cross-compile toolchain (Binutils, GCC, EGLIBC).
396 The <tt>CROSS</tt> prefix may vary depending on the <tt>--target</tt>
397 of the toolchain:
398 </p>
399 <pre class="code">
400 # PPC
401 make HOST_CC="gcc -m32" CROSS=powerpc-linux-gnu- TARGET=ppc
402 </pre>
403 <pre class="code">
404 # PPC/e500v2
405 make HOST_CC="gcc -m32" CROSS=powerpc-e500v2-linux-gnuspe- TARGET=ppcspe
406 </pre>
408 Whenever the <b>host OS and the target OS differ</b>, you need to specify
409 <tt>TARGET_SYS</tt> or you'll get assembler or linker errors. E.g. if
410 you're compiling on a Windows or OSX host for embedded Linux or Android,
411 you need to add <tt>TARGET_SYS=Linux</tt> to the examples above. For a
412 minimal target OS, you may need to disable the built-in allocator in
413 <tt>src/Makefile</tt> and use <tt>TARGET_SYS=Other</tt>.
414 </p>
416 <h2 id="embed">Embedding LuaJIT</h2>
418 LuaJIT is API-compatible with Lua 5.1. If you've already embedded Lua
419 into your application, you probably don't need to do anything to switch
420 to LuaJIT, except link with a different library:
421 </p>
422 <ul>
423 <li>It's strongly suggested to build LuaJIT separately using the supplied
424 build system. Please do <em>not</em> attempt to integrate the individual
425 source files into your build tree. You'll most likely get the internal build
426 dependencies wrong or mess up the compiler flags. Treat LuaJIT like any
427 other external library and link your application with either the dynamic
428 or static library, depending on your needs.</li>
429 <li>If you want to load C modules compiled for plain Lua
430 with <tt>require()</tt>, you need to make sure the public symbols
431 (e.g. <tt>lua_pushnumber</tt>) are exported, too:
432 <ul><li>On POSIX systems you can either link to the shared library
433 or link the static library into your application. In the latter case
434 you'll need to export all public symbols from your main executable
435 (e.g. <tt>-Wl,-E</tt> on Linux) and add the external dependencies
436 (e.g. <tt>-lm -ldl</tt> on Linux).</li>
437 <li>Since Windows symbols are bound to a specific DLL name, you need to
438 link to the <tt>lua51.dll</tt> created by the LuaJIT build (do not rename
439 the DLL). You may link LuaJIT statically on Windows only if you don't
440 intend to load Lua/C modules at runtime.
441 </li></ul>
442 </li>
443 <li>
444 If you're building a 64 bit application on OSX which links directly or
445 indirectly against LuaJIT, you need to link your main executable
446 with these flags:
447 <pre class="code">
448 -pagezero_size 10000 -image_base 100000000
449 </pre>
450 Also, it's recommended to <tt>rebase</tt> all (self-compiled) shared libraries
451 which are loaded at runtime on OSX/x64 (e.g. C extension modules for Lua).
452 See: <tt>man rebase</tt>
453 </li>
454 </ul>
455 <p>Additional hints for initializing LuaJIT using the C API functions:</p>
456 <ul>
457 <li>Here's a
458 <a href="http://lua-users.org/wiki/SimpleLuaApiExample"><span class="ext">&raquo;</span>&nbsp;simple example</a>
459 for embedding Lua or LuaJIT into your application.</li>
460 <li>Make sure you use <tt>luaL_newstate</tt>. Avoid using
461 <tt>lua_newstate</tt>, since this uses the (slower) default memory
462 allocator from your system (no support for this on x64).</li>
463 <li>Make sure you use <tt>luaL_openlibs</tt> and not the old Lua 5.0 style
464 of calling <tt>luaopen_base</tt> etc. directly.</li>
465 <li>To change or extend the list of standard libraries to load, copy
466 <tt>src/lib_init.c</tt> to your project and modify it accordingly.
467 Make sure the <tt>jit</tt> library is loaded or the JIT compiler
468 will not be activated.</li>
469 <li>The <tt>bit.*</tt> module for bitwise operations
470 is already built-in. There's no need to statically link
471 <a href="http://bitop.luajit.org/"><span class="ext">&raquo;</span>&nbsp;Lua BitOp</a> to your application.</li>
472 </ul>
474 <h2 id="distro">Hints for Distribution Maintainers</h2>
476 The LuaJIT build system has extra provisions for the needs of most
477 POSIX-based distributions. If you're a package maintainer for
478 a distribution, <em>please</em> make use of these features and
479 avoid patching, subverting, autotoolizing or messing up the build system
480 in unspeakable ways.
481 </p>
483 There should be absolutely no need to patch <tt>luaconf.h</tt> or any
484 of the Makefiles. And please do not hand-pick files for your packages &mdash;
485 simply use whatever <tt>make install</tt> creates. There's a reason
486 for all of the files <em>and</em> directories it creates.
487 </p>
489 The build system uses GNU make and auto-detects most settings based on
490 the host you're building it on. This should work fine for native builds,
491 even when sandboxed. You may need to pass some of the following flags to
492 <em>both</em> the <tt>make</tt> and the <tt>make install</tt> command lines
493 for a regular distribution build:
494 </p>
495 <ul>
496 <li><tt>PREFIX</tt> overrides the installation path and should usually
497 be set to <tt>/usr</tt>. Setting this also changes the module paths and
498 the <tt>-rpath</tt> of the shared library.</li>
499 <li><tt>DESTDIR</tt> is an absolute path which allows you to install
500 to a shadow tree instead of the root tree of the build system.</li>
501 <li>Have a look at the top-level <tt>Makefile</tt> and <tt>src/Makefile</tt>
502 for additional variables to tweak. The following variables <em>may</em> be
503 overridden, but it's <em>not</em> recommended, except for special needs
504 like cross-builds:
505 <tt>BUILDMODE, CC, HOST_CC, STATIC_CC, DYNAMIC_CC, CFLAGS, HOST_CFLAGS,
506 TARGET_CFLAGS, LDFLAGS, HOST_LDFLAGS, TARGET_LDFLAGS, TARGET_SHLDFLAGS,
507 TARGET_FLAGS, LIBS, HOST_LIBS, TARGET_LIBS, CROSS, HOST_SYS, TARGET_SYS
508 </tt></li>
509 </ul>
511 The build system has a special target for an amalgamated build, i.e.
512 <tt>make amalg</tt>. This compiles the LuaJIT core as one huge C file
513 and allows GCC to generate faster and shorter code. Alas, this requires
514 lots of memory during the build. This may be a problem for some users,
515 that's why it's not enabled by default. But it shouldn't be a problem for
516 most build farms. It's recommended that binary distributions use this
517 target for their LuaJIT builds.
518 </p>
520 The tl;dr version of the above:
521 </p>
522 <pre class="code">
523 make amalg PREFIX=/usr && \
524 make install PREFIX=/usr DESTDIR=/tmp/buildroot
525 </pre>
527 Finally, if you encounter any difficulties, please
528 <a href="contact.html">contact me</a> first, instead of releasing a broken
529 package onto unsuspecting users. Because they'll usually gonna complain
530 to me (the upstream) and not you (the package maintainer), anyway.
531 </p>
532 <br class="flush">
533 </div>
534 <div id="foot">
535 <hr class="hide">
536 Copyright &copy; 2005-2011 Mike Pall
537 <span class="noprint">
538 &middot;
539 <a href="contact.html">Contact</a>
540 </span>
541 </div>
542 </body>
543 </html>