aboutsummaryrefslogtreecommitdiffstatshomepage
path: root/libraries/LuaJIT-1.1.7/jitdoc/luajit_install.html
diff options
context:
space:
mode:
Diffstat (limited to 'libraries/LuaJIT-1.1.7/jitdoc/luajit_install.html')
-rw-r--r--libraries/LuaJIT-1.1.7/jitdoc/luajit_install.html340
1 files changed, 340 insertions, 0 deletions
diff --git a/libraries/LuaJIT-1.1.7/jitdoc/luajit_install.html b/libraries/LuaJIT-1.1.7/jitdoc/luajit_install.html
new file mode 100644
index 0000000..bc5a3cd
--- /dev/null
+++ b/libraries/LuaJIT-1.1.7/jitdoc/luajit_install.html
@@ -0,0 +1,340 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
2<html>
3<head>
4<title>Installing LuaJIT</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.build {
13 line-height: 1.2;
14}
15td.buildsys {
16 width: 11em;
17}
18td.buildcmd {
19 width: 10em;
20 font-family: Courier New, Courier, monospace;
21}
22tr.buildhead td {
23 /* font-family: inherit; ... not supported in IE *sigh* */
24 font-family: Verdana, Arial, Helvetica, sans-serif;
25 font-weight: bold;
26}
27</style>
28</head>
29<body>
30<div id="site">
31<a href="http://luajit.org/"><span>Lua<span id="logo">JIT</span></span></a>
32</div>
33<div id="head">
34<h1>Installing LuaJIT</h1>
35</div>
36<div id="nav">
37<ul><li>
38<a href="index.html">Index</a>
39</li><li>
40<a href="luajit.html">LuaJIT</a>
41<ul><li>
42<a href="luajit_features.html">Features</a>
43</li><li>
44<a class="current" href="luajit_install.html">Installation</a>
45</li><li>
46<a href="luajit_run.html">Running</a>
47</li><li>
48<a href="luajit_api.html">API Extensions</a>
49</li><li>
50<a href="luajit_intro.html">Introduction</a>
51</li><li>
52<a href="luajit_performance.html">Performance</a>
53</li><li>
54<a href="luajit_debug.html">Debugging</a>
55</li><li>
56<a href="luajit_changes.html">Changes</a>
57</li></ul>
58</li><li>
59<a href="coco.html">Coco</a>
60<ul><li>
61<a href="coco_portability.html">Portability</a>
62</li><li>
63<a href="coco_api.html">API Extensions</a>
64</li><li>
65<a href="coco_changes.html">Changes</a>
66</li></ul>
67</li><li>
68<a href="dynasm.html">DynASM</a>
69<ul><li>
70<a href="dynasm_features.html">Features</a>
71</li><li>
72<a href="dynasm_examples.html">Examples</a>
73</li></ul>
74</li><li>
75<a href="http://luajit.org/download.html">Download <span class="ext">&raquo;</span></a>
76</li></ul>
77</div>
78<div id="main">
79<p>
80LuaJIT is not much more difficult to install than Lua itself.
81Just unpack the distribution file, change into the newly created
82directory and follow the instructions below.
83</p>
84<p class="indent">
85For the impatient: <b><tt>make&nbsp;linux&nbsp;&amp;&amp;&nbsp;sudo&nbsp;make&nbsp;install</tt></b><br>
86Replace <tt>linux</tt> with e.g. <tt>bsd</tt> or <tt>macosx</tt> depending on your OS.
87</p>
88<p>
89In case you've missed this in <a href="luajit_features.html">Features</a>:
90LuaJIT only works on x86 (i386+) systems right now. Support for
91other architectures may be added in future versions.
92</p>
93
94<h2>Configuring LuaJIT</h2>
95<p>
96LuaJIT is (deliberately) <em>not</em> autoconfigured &mdash; the
97defaults should work fine on most systems. But please check the
98system-specific instructions below.
99</p>
100<p>
101The following three files hold all configuration information:
102</p>
103<ul>
104<li><tt>Makefile</tt> holds settings for installing LuaJIT.</li>
105<li><tt>src/Makefile</tt> holds settings for compiling LuaJIT.</li>
106<li><tt>src/luaconf.h</tt> sets a multitude of configuration
107variables.</li>
108</ul>
109<p>
110If this is your first build then it's better not to give into
111the temptation to tweak every little setting. The standard
112configuration provides sensible defaults (IMHO).
113</p>
114<p>
115One particular setting you might want to change is the installation
116path. Note that you need to modify both the top-level <tt>Makefile</tt>
117and <tt>src/luaconf.h</tt> (right at the start) to take
118effect.
119</p>
120<p>
121If you have trouble getting Coco to work, you can disable it by
122uncommenting the <tt>COCOFLAGS= -DCOCO_DISABLE</tt> line in
123<tt>src/Makefile</tt>. But note that this effectively disables
124yielding from coroutines for JIT compiled functions.
125</p>
126<p>
127A few more settings need to be changed if you want to
128<a href="luajit_debug.html">Debug LuaJIT</a> <em>itself</em>.
129Application debugging can be turned on/off at runtime.
130</p>
131
132<h3>Upgrading From Previous Versions</h3>
133<p>
134It's important to keep the LuaJIT core and the add-on modules in sync.
135Be sure to delete any old versions of LuaJIT modules from the
136Lua module search path (check the current directory, too!).
137</p>
138<p>
139Lua files compiled to bytecode may be incompatible if the underlying
140Lua core has changed (like from Lua&nbsp;5.1 alpha to Lua&nbsp;5.1
141final between LuaJIT&nbsp;1.0.3 and LuaJIT&nbsp;1.1.0). The same
142applies to any
143<a href="http://lua-users.org/wiki/BuildingModules"><span class="ext">&raquo;</span>&nbsp;loadable C modules</a>
144(shared libraries, DLLs) which need to be recompiled with the new
145Lua header files.
146</p>
147<p>
148Compiled bytecode and loadable C modules are fully compatible and
149can be freely exchanged between LuaJIT and the <em>same</em>
150version of Lua it is based on. Please verify that <tt>LUA_RELEASE</tt>
151in <tt>src/lua.h</tt> is the same in both distributions.
152</p>
153
154<h2>Building LuaJIT</h2>
155
156<h3>Makefile Targets</h3>
157<p>
158The Makefiles have a number of targets for various operating systems:
159</p>
160
161<div class="tablewrap">
162<table class="build">
163<tr class="buildhead"><td class="buildsys">System</td><td class="buildcmd">Build Command</td><td>Notes</td></tr>
164<tr class="odd"><td class="buildsys">Linux i386</td><td class="buildcmd">make linux</td><td></td></tr>
165<tr class="even"><td class="buildsys">BSD i386</td><td class="buildcmd">make bsd</td><td>FreeBSD, NetBSD or OpenBSD</td></tr>
166<tr class="odd"><td class="buildsys">Mac OS X on Intel</td><td class="buildcmd">make macosx</td><td>Check <tt>src/Makefile</tt> for OS X &lt; 10.4</td></tr>
167<tr class="even"><td class="buildsys">Solaris x86</td><td class="buildcmd">make solaris</td><td>GCC only, SunCC miscompiles LuaJIT</td></tr>
168<tr class="odd"><td class="buildsys">MinGW (Win32)</td><td class="buildcmd">make mingw</td><td>cross-MinGW: must be 1st in PATH</td></tr>
169<tr class="even"><td class="buildsys">Cygwin</td><td class="buildcmd">make cygwin</td><td></td></tr>
170<tr class="odd"><td class="buildsys">POSIX on x86</td><td class="buildcmd">make posix</td><td>Check <a href="coco_portability.html">Portability Req. for Coco</a>, too</td></tr>
171<tr class="even"><td class="buildsys">Generic x86</td><td class="buildcmd">make generic</td><td>Check <a href="coco_portability.html">Portability Req. for Coco</a>, too</td></tr>
172</table>
173</div>
174
175<p>
176You may want to enable interactive line editing for the stand-alone
177executable. There are extra targets for Linux, BSD and Mac OS X:
178<tt>make&nbsp;linux_rl</tt>, <tt>make&nbsp;bsd_rl</tt>
179and <tt>make&nbsp;macosx_rl</tt>.
180</p>
181
182<h3>MSVC (Win32)</h3>
183<p>
184First check out <tt>etc\luavs.bat</tt> if it suits your needs. Then try
185running it from the MSVC command prompt (start it from the toplevel directory).
186</p>
187<p>
188Another option is to set up your own MSVC project:
189</p>
190<p>
191Change to the <tt>src</tt> directory
192and create a new DLL project for <tt>lua51.dll</tt>.
193Add all C files to it except for <tt>lua.c</tt>, <tt>luac.c</tt>
194and <tt>print.c</tt>. Add the <tt>..\dynasm</tt> directory
195to the include path and build the DLL.
196</p>
197<p>
198Next create a new EXE project for <tt>luajit.exe</tt>.
199Add <tt>lua.c</tt> to it and link with the import library
200<tt>lua51.lib</tt> created for <tt>lua51.dll</tt>. Build
201the executable.
202</p>
203
204<h2>Installation</h2>
205
206<h3>POSIX systems</h3>
207<p>
208Run <tt>make&nbsp;install</tt> from the top-level directory.
209You probably need to be the root user before doing so, i.e. use
210<tt>sudo&nbsp;make&nbsp;install</tt> or <tt>su&nbsp;-&nbsp;root</tt>
211before the <tt>make&nbsp;install</tt>.
212</p>
213<p>
214By default this installs only:<br>
215<tt>&nbsp;&nbsp;/usr/local/bin/<strong>luajit</strong></tt> &mdash; The stand-alone executable.<br>
216<tt>&nbsp;&nbsp;/usr/local/lib/lua/5.1</tt> &mdash; C module directory.<br>
217<tt>&nbsp;&nbsp;/usr/local/share/lua/5.1</tt> &mdash; Lua module directory.<br>
218<tt>&nbsp;&nbsp;/usr/local/share/lua/5.1/<strong>jit/*.lua</strong></tt> &mdash;
219<tt>jit.*</tt> modules.<br>
220</p>
221<p>
222The Lua docs and includes are not installed to avoid overwriting
223an existing Lua installation. In any case these are identical
224to the version of Lua that LuaJIT is based on. If you want
225to install them, edit the top-level makefile (look for <tt>###</tt>).
226</p>
227<p>
228The stand-alone Lua bytecode compiler <tt>luac</tt> is neither
229built nor installed, for the same reason. If you really need it,
230you may be better off with <tt>luac</tt> built from the original Lua
231distribution (use the <em>same</em> version your copy of LuaJIT
232is based on). This avoids dragging in most of LuaJIT which is not
233needed for the pure bytecode compiler. You can also use the bare-bones
234Lua to bytecode translator <tt>luac.lua</tt> (look in the <tt>test</tt>
235directory of the original Lua distribution).
236</p>
237
238<h3>Windows</h3>
239<p>
240Copy <tt>luajit.exe</tt> and <tt>lua51.dll</tt>
241to a newly created directory (any location is ok). Add <tt>lua</tt>
242and <tt>lua\jit</tt> directories below it and copy all Lua files
243from the <tt>jit</tt> directory of the distribution to the latter directory.
244</p>
245<p>
246There are no hardcoded
247absolute path names &mdash; all modules are loaded relative to the
248directory where <tt>luajit.exe</tt> is installed
249(see <tt>src/luaconf.h</tt>).
250</p>
251
252<h2 id="embedding">Embedding LuaJIT</h2>
253<p>
254It's strongly recommended that you build the stand-alone executable
255with your toolchain and verify that it works <em>before</em> starting
256to embed LuaJIT into an application. The stand-alone executable is
257also useful later on, when you want to experiment with code snippets
258or try out some Lua files.
259</p>
260<p>
261Please consult the Lua docs for general information about how to
262embed Lua into your application. The following list only shows
263the additional steps needed for embedding LuaJIT:
264</p>
265<ul>
266<li>You need to add the LuaJIT library functions by running
267<tt>luaopen_jit()</tt> after all the other standard library functions.
268The modified <tt>src/linit.c</tt> used by the stand-alone executable
269already does this for you.</li>
270<li><em>Caveat:</em> LuaJIT is based on Lua 5.1 which
271means the <tt>luaopen_*()</tt> functions <em>must not</em>
272be called directly. See <tt>src/linit.c</tt> for the proper way to
273run them. You'll get an error initializing the <tt>io</tt> library
274if you don't follow these instructions.</li>
275<li>To use the optimizer (strongly recommended) you need to:
276<ul>
277<li>Install the optimizer modules <tt>jit.opt</tt> and
278<tt>jit.opt_inline</tt> relative to the Lua module path
279(you've probably modified it &mdash; see <tt>src/luaconf.h</tt>):<br>
280<tt>jit/opt.lua</tt><br>
281<tt>jit/opt_inline.lua</tt></li>
282<li>If you want to ship a single executable then you may want to
283embed the optimizer modules into your application (but don't loose
284time with this during the early development phase). This involves:
285<ul>
286<li>Compile the two modules to bytecode
287(using <tt>luac&nbsp;-s</tt> from a plain Lua installation).</li>
288<li>Convert them to C include files (search for "Lua&nbsp;bin2c").</li>
289<li>On Windows you can also put the compiled bytecode into a resource
290(search for "Lua&nbsp;bin2res").</li>
291<li>Load the bytecode with <tt>luaL_loadbuffer</tt> (but don't run it).</li>
292<li>Put the resulting functions into <tt>package.preload["jit.opt"]</tt>
293and <tt>package.preload["jit.opt_inline"]</tt>.</li>
294</ul></li>
295<li>Activate the LuaJIT optimizer from Lua code to be run at startup:
296<tt>&nbsp;&nbsp;require("jit.opt").start()</tt><br>
297Or use equivalent C code. See <tt>dojitopt()</tt> in <tt>src/lua.c</tt>.</li>
298</ul></li>
299<li>All other LuaJIT specific modules (<tt>jit.*</tt>) are for debugging only.
300They do not need to be shipped with an application. But they may be quite
301useful, anyway (especially <tt>jit.trace</tt>).</li>
302<li>DynASM is only needed while <em>building</em> LuaJIT. It's not
303needed while running LuaJIT and there is no point in shipping or
304installing it together with an application.</li>
305<li>In case you want to strip some of the standard libraries from
306your application: The optimizer modules need several functions from
307the base library and the string library (and of course the LuaJIT
308core libraries). The io library is only used to print a fatal error
309message (you may want to replace it). The optional modules
310for debugging depend on a few more library functions &mdash;
311please check the source.</li>
312</ul>
313<p>
314Although the very liberal LuaJIT
315<a href="http://www.opensource.org/licenses/mit-license.php"><span class="ext">&raquo;</span>&nbsp;license</a>
316does not require any acknowledgment whatsoever, it would be appreciated
317if you give some credit in the docs (or the "About" box) of your application.
318A simple line like:<br>
319<tt>&nbsp;&nbsp;This product includes LuaJIT, http://luajit.org/</tt><br>
320would be nice. Please do not include any E-Mail addresses. Thank you!
321</p>
322<p>
323I'm always interested where LuaJIT can be put to good use in applications.
324Please <a href="contact.html">tell me</a>
325or better yet write a few lines about your project to the
326<a href="http://www.lua.org/lua-l.html"><span class="ext">&raquo;</span>&nbsp;Lua mailing list</a>.
327Thank you!
328</p>
329<br class="flush">
330</div>
331<div id="foot">
332<hr class="hide">
333Copyright &copy; 2005-2011 Mike Pall
334<span class="noprint">
335&middot;
336<a href="contact.html">Contact</a>
337</span>
338</div>
339</body>
340</html>
generated by cgit v1.1 at 2025-01-13 11:03:26 +0000