aboutsummaryrefslogtreecommitdiffstatshomepage
path: root/libraries/luajit-2.0/doc/install.html
diff options
context:
space:
mode:
Diffstat (limited to 'libraries/luajit-2.0/doc/install.html')
-rw-r--r--libraries/luajit-2.0/doc/install.html543
1 files changed, 0 insertions, 543 deletions
diff --git a/libraries/luajit-2.0/doc/install.html b/libraries/luajit-2.0/doc/install.html
deleted file mode 100644
index 07c55fa..0000000
--- a/libraries/luajit-2.0/doc/install.html
+++ /dev/null
@@ -1,543 +0,0 @@
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">
12table.compat {
13 line-height: 1.2;
14 width: 600px;
15}
16table.compat td {
17 border: 1px solid #bfcfff;
18 font-size: 90%;
19 height: 2.5em;
20}
21table.compat tr.compathead td {
22 font-weight: bold;
23 border-bottom: 2px solid #bfcfff;
24}
25tr.compathead td.compatos {
26 vertical-align: top;
27}
28table.compat td.compatcpu {
29 width: 16%;
30 border-right: 2px solid #bfcfff;
31}
32td.compatos {
33 width: 21%;
34 vertical-align: middle;
35}
36td.compatno {
37 background-color: #d0d0d0;
38}
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>
87LuaJIT is only distributed as a source package. This page explains
88how to build and install LuaJIT with different operating systems
89and C&nbsp;compilers.
90</p>
91<p>
92For the impatient (on POSIX systems):
93</p>
94<pre class="code">
95make &amp;&amp; sudo make install
96</pre>
97<p>
98LuaJIT currently builds out-of-the box on most systems.
99Here's the compatibility matrix for the supported combinations of
100operating 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>
146
147<h2>Configuring LuaJIT</h2>
148<p>
149The standard configuration should work fine for most installations.
150Usually there is no need to tweak the settings. The following files
151hold 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
156only).</li>
157<li><tt>src/Makefile</tt> has settings for <b>compiling</b> LuaJIT
158under POSIX, MinGW or Cygwin.</li>
159<li><tt>src/msvcbuild.bat</tt> has settings for compiling LuaJIT with
160MSVC or WinSDK.</li>
161</ul>
162<p>
163Please read the instructions given in these files, before changing
164any settings.
165</p>
166
167<h2 id="posix">POSIX Systems (Linux, OSX, *BSD etc.)</h2>
168<h3>Prerequisites</h3>
169<p>
170Depending on your distribution, you may need to install a package for
171GCC, the development headers and/or a complete SDK. E.g. on a current
172Debian/Ubuntu, install <tt>libc6-dev</tt> with the package manager.
173</p>
174<p>
175Download the current source package of LuaJIT (pick the .tar.gz),
176if you haven't already done so. Move it to a directory of your choice,
177open a terminal window and change to this directory. Now unpack the archive
178and change to the newly created directory:
179</p>
180<pre class="code">
181tar zxf LuaJIT-2.0.0-beta9.tar.gz
182cd LuaJIT-2.0.0-beta9</pre>
183<h3>Building LuaJIT</h3>
184<p>
185The supplied Makefiles try to auto-detect the settings needed for your
186operating system and your compiler. They need to be run with GNU Make,
187which is probably the default on your system, anyway. Simply run:
188</p>
189<pre class="code">
190make
191</pre>
192<p>
193This always builds a native x86, x64 or PPC binary, depending on the host OS
194you're running this command on. Check the section on
195<a href="#cross">cross-compilation</a> for more options.
196</p>
197<p>
198By default, modules are only searched under the prefix <tt>/usr/local</tt>.
199You 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">
203make PREFIX=/home/myself/lj2
204</pre>
205<p>
206Note for OSX: <tt>MACOSX_DEPLOYMENT_TARGET</tt> is set to <tt>10.4</tt>
207in <tt>src/Makefile</tt>. Change it, if you want to build on an older version.
208</p>
209<h3>Installing LuaJIT</h3>
210<p>
211The 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
214to write to this path. So, assuming sudo is installed on your system,
215run the following command and enter your sudo password:
216</p>
217<pre class="code">
218sudo make install
219</pre>
220<p>
221Otherwise specify the directory prefix as an absolute path, e.g.:
222</p>
223<pre class="code">
224make install PREFIX=/home/myself/lj2
225</pre>
226<p>
227Obviously the prefixes given during build and installation need to be the same.
228</p>
229<p style="color: #c00000;">
230Note: to avoid overwriting a previous version, the beta test releases
231only 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
233for convenience, with a command like this:
234</p>
235<pre class="code" style="color: #c00000;">
236sudo ln -sf luajit-2.0.0-beta9&nbsp;/usr/local/bin/luajit
237</pre>
238
239<h2 id="windows">Windows Systems</h2>
240<h3>Prerequisites</h3>
241<p>
242Either 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
245GCC plus the required development headers.
246</p>
247<p>
248Or 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>
250works just fine, but only contains an x86 compiler.
251</p>
252<p>
253The freely downloadable
254<a href="http://msdn.microsoft.com/en-us/windowsserver/bb980924.aspx"><span class="ext">&raquo;</span>&nbsp;Windows SDK</a>
255only comes with command line tools, but this is all you need to build LuaJIT.
256It contains x86 and x64 compilers.
257</p>
258<p>
259Next, 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>
263<p>
264Open a "Visual Studio .NET Command Prompt", <tt>cd</tt> to the
265directory where you've unpacked the sources and run these commands:
266</p>
267<pre class="code">
268cd src
269msvcbuild
270</pre>
271<p>
272Then follow the installation instructions below.
273</p>
274<h3>Building with the Windows SDK</h3>
275<p>
276Open a "Windows SDK Command Shell" and select the x86 compiler:
277</p>
278<pre class="code">
279setenv /release /x86
280</pre>
281<p>
282Or select the x64 compiler:
283</p>
284<pre class="code">
285setenv /release /x64
286</pre>
287<p>
288Then <tt>cd</tt> to the directory where you've unpacked the sources
289and run these commands:
290</p>
291<pre class="code">
292cd src
293msvcbuild
294</pre>
295<p>
296Then follow the installation instructions below.
297</p>
298<h3>Building with MinGW or Cygwin</h3>
299<p>
300Open a command prompt window and make sure the MinGW or Cygwin programs
301are in your path. Then <tt>cd</tt> to the directory where
302you've unpacked the sources and run this command for MinGW:
303</p>
304<pre class="code">
305mingw32-make
306</pre>
307<p>
308Or this command for Cygwin:
309</p>
310<pre class="code">
311make
312</pre>
313<p>
314Then follow the installation instructions below.
315</p>
316<h3>Installing LuaJIT</h3>
317<p>
318Copy <tt>luajit.exe</tt> and <tt>lua51.dll</tt> (built in the <tt>src</tt>
319directory) to a newly created directory (any location is ok).
320Add <tt>lua</tt> and <tt>lua\jit</tt> directories below it and copy
321all Lua files from the <tt>lib</tt> directory of the distribution
322to the latter directory.
323</p>
324<p>
325There are no hardcoded
326absolute path names &mdash; all modules are loaded relative to the
327directory where <tt>luajit.exe</tt> is installed
328(see <tt>src/luaconf.h</tt>).
329</p>
330
331<h2 id="cross">Cross-compiling LuaJIT</h2>
332<p>
333The build system has limited support for cross-compilation. For details
334check the comments in <tt>src/Makefile</tt>. Here are some popular examples:
335</p>
336<p>
337You can cross-compile to a <b>32 bit binary on a multilib x64 OS</b> by
338installing the multilib development packages (e.g. <tt>libc6-dev-i386</tt>
339on Debian/Ubuntu) and running:
340</p>
341<pre class="code">
342make CC="gcc -m32"
343</pre>
344<p>
345You can cross-compile for a <b>Windows target on Debian/Ubuntu</b> by
346installing the <tt>mingw32</tt> package and running:
347</p>
348<pre class="code">
349make HOST_CC="gcc -m32" CROSS=i586-mingw32msvc- TARGET_SYS=Windows
350</pre>
351<p>
352You can cross-compile for an <b>ARM target</b> on an x86 or x64 host
353system using a standard GNU cross-compile toolchain (Binutils, GCC,
354EGLIBC). The <tt>CROSS</tt> prefix may vary depending on the
355<tt>--target</tt> of the toolchain:
356</p>
357<pre class="code">
358make HOST_CC="gcc -m32" CROSS=arm-linux-gnueabi-
359</pre>
360<p>
361You 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>.
362The environment variables need to match the install locations and the
363desired target platform. E.g. Android&nbsp;2.2 corresponds to ABI level&nbsp;8:
364</p>
365<pre class="code">
366NDK=/opt/android/ndk
367NDKABI=8
368NDKVER=$NDK/toolchains/arm-linux-androideabi-4.4.3
369NDKP=$NDKVER/prebuilt/linux-x86/bin/arm-linux-androideabi-
370NDKF="--sysroot $NDK/platforms/android-$NDKABI/arch-arm"
371make HOST_CC="gcc -m32" CROSS=$NDKP TARGET_FLAGS="$NDKF"
372</pre>
373<p>
374You 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>.
375The environment variables need to match the iOS SDK version:
376</p>
377<p style="font-size: 8pt;">
378Note: <b>the JIT compiler is disabled for iOS</b>, because regular iOS Apps
379are not allowed to generate code at runtime. You'll only get the performance
380of the LuaJIT interpreter on iOS. This is still faster than plain Lua, but
381much slower than the JIT compiler. Please complain to Apple, not me.
382Or use Android. :-p
383</p>
384<pre class="code">
385ISDK=/Developer/Platforms/iPhoneOS.platform/Developer
386ISDKVER=iPhoneOS4.3.sdk
387ISDKP=$ISDK/usr/bin/
388ISDKF="-arch armv6 -isysroot $ISDK/SDKs/$ISDKVER"
389make HOST_CC="gcc -m32 -arch i386" CROSS=$ISDKP TARGET_FLAGS="$ISDKF" \
390 TARGET_SYS=iOS
391</pre>
392<p>
393You 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
395GNU cross-compile toolchain (Binutils, GCC, EGLIBC).
396The <tt>CROSS</tt> prefix may vary depending on the <tt>--target</tt>
397of the toolchain:
398</p>
399<pre class="code">
400# PPC
401make HOST_CC="gcc -m32" CROSS=powerpc-linux-gnu-
402</pre>
403<pre class="code">
404# PPC/e500v2
405make HOST_CC="gcc -m32" CROSS=powerpc-e500v2-linux-gnuspe-
406</pre>
407<p>
408Whenever 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
410you're compiling on a Windows or OSX host for embedded Linux or Android,
411you need to add <tt>TARGET_SYS=Linux</tt> to the examples above. For a
412minimal 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>
415
416<h2 id="embed">Embedding LuaJIT</h2>
417<p>
418LuaJIT is API-compatible with Lua 5.1. If you've already embedded Lua
419into your application, you probably don't need to do anything to switch
420to LuaJIT, except link with a different library:
421</p>
422<ul>
423<li>It's strongly suggested to build LuaJIT separately using the supplied
424build system. Please do <em>not</em> attempt to integrate the individual
425source files into your build tree. You'll most likely get the internal build
426dependencies wrong or mess up the compiler flags. Treat LuaJIT like any
427other external library and link your application with either the dynamic
428or static library, depending on your needs.</li>
429<li>If you want to load C modules compiled for plain Lua
430with <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
433or link the static library into your application. In the latter case
434you'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
438link to the <tt>lua51.dll</tt> created by the LuaJIT build (do not rename
439the DLL). You may link LuaJIT statically on Windows only if you don't
440intend to load Lua/C modules at runtime.
441</li></ul>
442</li>
443<li>
444If you're building a 64 bit application on OSX which links directly or
445indirectly against LuaJIT, you need to link your main executable
446with these flags:
447<pre class="code">
448-pagezero_size 10000 -image_base 100000000
449</pre>
450Also, it's recommended to <tt>rebase</tt> all (self-compiled) shared libraries
451which are loaded at runtime on OSX/x64 (e.g. C extension modules for Lua).
452See: <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>
459for 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
462allocator 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
464of 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.
467Make sure the <tt>jit</tt> library is loaded or the JIT compiler
468will not be activated.</li>
469<li>The <tt>bit.*</tt> module for bitwise operations
470is 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>
473
474<h2 id="distro">Hints for Distribution Maintainers</h2>
475<p>
476The LuaJIT build system has extra provisions for the needs of most
477POSIX-based distributions. If you're a package maintainer for
478a distribution, <em>please</em> make use of these features and
479avoid patching, subverting, autotoolizing or messing up the build system
480in unspeakable ways.
481</p>
482<p>
483There should be absolutely no need to patch <tt>luaconf.h</tt> or any
484of the Makefiles. And please do not hand-pick files for your packages &mdash;
485simply use whatever <tt>make install</tt> creates. There's a reason
486for all of the files <em>and</em> directories it creates.
487</p>
488<p>
489The build system uses GNU make and auto-detects most settings based on
490the host you're building it on. This should work fine for native builds,
491even 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
493for a regular distribution build:
494</p>
495<ul>
496<li><tt>PREFIX</tt> overrides the installation path and should usually
497be set to <tt>/usr</tt>. Setting this also changes the module paths and
498the <tt>-rpath</tt> of the shared library.</li>
499<li><tt>DESTDIR</tt> is an absolute path which allows you to install
500to 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>
502for additional variables to tweak. The following variables <em>may</em> be
503overridden, but it's <em>not</em> recommended, except for special needs
504like cross-builds:
505<tt>BUILDMODE, CC, HOST_CC, STATIC_CC, DYNAMIC_CC, CFLAGS, HOST_CFLAGS,
506TARGET_CFLAGS, LDFLAGS, HOST_LDFLAGS, TARGET_LDFLAGS, TARGET_SHLDFLAGS,
507TARGET_FLAGS, LIBS, HOST_LIBS, TARGET_LIBS, CROSS, HOST_SYS, TARGET_SYS
508</tt></li>
509</ul>
510<p>
511The 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
513and allows GCC to generate faster and shorter code. Alas, this requires
514lots of memory during the build. This may be a problem for some users,
515that's why it's not enabled by default. But it shouldn't be a problem for
516most build farms. It's recommended that binary distributions use this
517target for their LuaJIT builds.
518</p>
519<p>
520The tl;dr version of the above:
521</p>
522<pre class="code">
523make amalg PREFIX=/usr && \
524make install PREFIX=/usr DESTDIR=/tmp/buildroot
525</pre>
526<p>
527Finally, if you encounter any difficulties, please
528<a href="contact.html">contact me</a> first, instead of releasing a broken
529package onto unsuspecting users. Because they'll usually gonna complain
530to 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">
536Copyright &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>
generated by cgit v1.1 at 2024-07-01 04:54:10 +0000