doc/install.html

   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;
  15 }
  16 table.compat td {
  17   border: 1px solid #bfcfff;
  18   font-size: 90%;
  19   height: 2.5em;
  20 }
  21 table.compat tr.compathead td {
  22   font-weight: bold;
  23   border-bottom: 2px solid #bfcfff;
  24 }
  25 tr.compathead td.compatos {
  26   vertical-align: top;
  27 }
  28 table.compat td.compatcpu {
  29   width: 16%;
  30   border-right: 2px solid #bfcfff;
  31 }
  32 td.compatos {
  33   width: 21%;
  34   vertical-align: middle;
  35 }
  36 td.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_int64.html">64 bit Integers</a>
  66 </li><li>
  67 <a href="ext_ffi_semantics.html">FFI Semantics</a>
  68 </li></ul>
  69 </li><li>
  70 <a href="ext_jit.html">jit.* Library</a>
  71 </li><li>
  72 <a href="ext_c_api.html">Lua/C API</a>
  73 </li></ul>
  74 </li><li>
  75 <a href="status.html">Status</a>
  76 <ul><li>
  77 <a href="changes.html">Changes</a>
  78 </li></ul>
  79 </li><li>
  80 <a href="faq.html">FAQ</a>
  81 </li><li>
  82 <a href="http://luajit.org/performance.html">Performance <span class="ext">&raquo;</span></a>
  83 </li><li>
  84 <a href="http://luajit.org/download.html">Download <span class="ext">&raquo;</span></a>
  85 </li></ul>
  86 </div>
  87 <div id="main">
  88 <p>
  89 LuaJIT is only distributed as a source package. This page explains
  90 how to build and install LuaJIT with different operating systems
  91 and C&nbsp;compilers.
  92 </p>
  93 <p>
  94 For the impatient (on POSIX systems):
  95 </p>
  96 <pre class="code">
  97 make &amp;&amp; sudo make install
  98 </pre>
  99 <p>
 100 LuaJIT currently builds out-of-the box on most systems.
 101 Here's the compatibility matrix for the supported combinations of
 102 operating system, CPU and compilers:
 103 </p>
 104 <table class="compat">
 105 <tr class="compathead">
 106 <td class="compatcpu">CPU / OS</td>
 107 <td class="compatos"><a href="#posix">Linux</a></td>
 108 <td class="compatos"><a href="#posix">OSX<br>10.3-10.6</a></td>
 109 <td class="compatos"><a href="#posix">*BSD, other</a></td>
 110 <td class="compatos"><a href="#windows">Windows<br>98/XP/Vista/7</a></td>
 111 </tr>
 112 <tr class="odd separate">
 113 <td class="compatcpu">x86 (32 bit)</td>
 114 <td class="compatos">GCC 4.x<br>GCC 3.4</td>
 115 <td class="compatos">GCC 4.x<br>GCC 3.4</td>
 116 <td class="compatos">GCC 4.x<br>GCC 3.4</td>
 117 <td class="compatos">MSVC, MSVC/EE<br>WinSDK<br>MinGW, Cygwin</td>
 118 </tr>
 119 <tr class="even">
 120 <td class="compatcpu">x64 (64 bit)</td>
 121 <td class="compatos">GCC 4.x</td>
 122 <td class="compatos">GCC 4.x</td>
 123 <td class="compatos compatno">&nbsp;</td>
 124 <td class="compatos">MSVC + SDK v7.0<br>WinSDK v7.0</td>
 125 </tr>
 126 <tr class="odd">
 127 <td class="compatcpu">PPC/e500v2</td>
 128 <td class="compatos">GCC 4.3+</td>
 129 <td class="compatos compatno">&nbsp;</td>
 130 <td class="compatos compatno">&nbsp;</td>
 131 <td class="compatos compatno">&nbsp;</td>
 132 </tr>
 133 </table>
 134
 135 <h2>Configuring LuaJIT</h2>
 136 <p>
 137 The standard configuration should work fine for most installations.
 138 Usually there is no need to tweak the settings. The following files
 139 hold all user-configurable settings:
 140 </p>
 141 <ul>
 142 <li><tt>src/luaconf.h</tt> sets some configuration variables.</li>
 143 <li><tt>Makefile</tt> has settings for <b>installing</b> LuaJIT (POSIX
 144 only).</li>
 145 <li><tt>src/Makefile</tt> has settings for <b>compiling</b> LuaJIT
 146 under POSIX, MinGW or Cygwin.</li>
 147 <li><tt>src/msvcbuild.bat</tt> has settings for compiling LuaJIT with
 148 MSVC or WinSDK.</li>
 149 </ul>
 150 <p>
 151 Please read the instructions given in these files, before changing
 152 any settings.
 153 </p>
 154
 155 <h2 id="posix">POSIX Systems (Linux, OSX, *BSD etc.)</h2>
 156 <h3>Prerequisites</h3>
 157 <p>
 158 Depending on your distribution, you may need to install a package for
 159 GCC, the development headers and/or a complete SDK. E.g. on a current
 160 Debian/Ubuntu, install <tt>libc6-dev</tt> with the package manager.
 161 </p>
 162 <p>
 163 Download the current source package of LuaJIT (pick the .tar.gz),
 164 if you haven't already done so. Move it to a directory of your choice,
 165 open a terminal window and change to this directory. Now unpack the archive
 166 and change to the newly created directory:
 167 </p>
 168 <pre class="code">
 169 tar zxf LuaJIT-2.0.0-beta5.tar.gz
 170 cd LuaJIT-2.0.0-beta5</pre>
 171 <h3>Building LuaJIT</h3>
 172 <p>
 173 The supplied Makefiles try to auto-detect the settings needed for your
 174 operating system and your compiler. They need to be run with GNU Make,
 175 which is probably the default on your system, anyway. Simply run:
 176 </p>
 177 <pre class="code">
 178 make
 179 </pre>
 180 <p>
 181 This always builds a native x86, x64 or PPC binary, depending on the host OS
 182 you're running this command on. Check the section on
 183 <a href="#cross">cross-compilation</a> for more options.
 184 </p>
 185 <p>
 186 By default, modules are only searched under the prefix <tt>/usr/local</tt>.
 187 You can add an extra prefix to the search paths by appending the
 188 <tt>PREFIX</tt> option, e.g.:
 189 </p>
 190 <pre class="code">
 191 make PREFIX=/home/myself/lj2
 192 </pre>
 193 <p>
 194 Note for OSX: <tt>MACOSX_DEPLOYMENT_TARGET</tt> is set to <tt>10.4</tt>
 195 in <tt>src/Makefile</tt>. Change it, if you want to build on an older version.
 196 </p>
 197 <h3>Installing LuaJIT</h3>
 198 <p>
 199 The top-level Makefile installs LuaJIT by default under
 200 <tt>/usr/local</tt>, i.e. the executable ends up in
 201 <tt>/usr/local/bin</tt> and so on. You need root privileges
 202 to write to this path. So, assuming sudo is installed on your system,
 203 run the following command and enter your sudo password:
 204 </p>
 205 <pre class="code">
 206 sudo make install
 207 </pre>
 208 <p>
 209 Otherwise specify the directory prefix as an absolute path, e.g.:
 210 </p>
 211 <pre class="code">
 212 make install PREFIX=/home/myself/lj2
 213 </pre>
 214 <p>
 215 Obviously the prefixes given during build and installation need to be the same.
 216 </p>
 217 <p style="color: #c00000;">
 218 Note: to avoid overwriting a previous version, the beta test releases
 219 only install the LuaJIT executable under the versioned name (i.e.
 220 <tt>luajit-2.0.0-beta5</tt>). You probably want to create a symlink
 221 for convenience, with a command like this:
 222 </p>
 223 <pre class="code" style="color: #c00000;">
 224 sudo ln -sf luajit-2.0.0-beta5&nbsp;/usr/local/bin/luajit
 225 </pre>
 226
 227 <h2 id="windows">Windows Systems</h2>
 228 <h3>Prerequisites</h3>
 229 <p>
 230 Either install one of the open source SDKs
 231 (<a href="http://mingw.org/"><span class="ext">&raquo;</span>&nbsp;MinGW</a> or
 232 <a href="http://www.cygwin.com/"><span class="ext">&raquo;</span>&nbsp;Cygwin</a>), which come with a modified
 233 GCC plus the required development headers.
 234 </p>
 235 <p>
 236 Or install Microsoft's Visual C++ (MSVC). The freely downloadable
 237 <a href="http://www.microsoft.com/Express/VC/"><span class="ext">&raquo;</span>&nbsp;Express Edition</a>
 238 works just fine, but only contains an x86 compiler.
 239 </p>
 240 <p>
 241 The freely downloadable
 242 <a href="http://msdn.microsoft.com/en-us/windowsserver/bb980924.aspx"><span class="ext">&raquo;</span>&nbsp;Windows SDK</a>
 243 only comes with command line tools, but this is all you need to build LuaJIT.
 244 It contains x86 and x64 compilers.
 245 </p>
 246 <p>
 247 Next, download the source package and unpack it using an archive manager
 248 (e.g. the Windows Explorer) to a directory of your choice.
 249 </p>
 250 <h3>Building with MSVC</h3>
 251 <p>
 252 Open a "Visual Studio .NET Command Prompt", <tt>cd</tt> to the
 253 directory where you've unpacked the sources and run these commands:
 254 </p>
 255 <pre class="code">
 256 cd src
 257 msvcbuild
 258 </pre>
 259 <p>
 260 Then follow the installation instructions below.
 261 </p>
 262 <h3>Building with the Windows SDK</h3>
 263 <p>
 264 Open a "Windows SDK Command Shell" and select the x86 compiler:
 265 </p>
 266 <pre class="code">
 267 setenv /release /x86
 268 </pre>
 269 <p>
 270 Or select the x64 compiler:
 271 </p>
 272 <pre class="code">
 273 setenv /release /x64
 274 </pre>
 275 <p>
 276 Then <tt>cd</tt> to the directory where you've unpacked the sources
 277 and run these commands:
 278 </p>
 279 <pre class="code">
 280 cd src
 281 msvcbuild
 282 </pre>
 283 <p>
 284 Then follow the installation instructions below.
 285 </p>
 286 <h3>Building with MinGW or Cygwin</h3>
 287 <p>
 288 Open a command prompt window and make sure the MinGW or Cygwin programs
 289 are in your path. Then <tt>cd</tt> to the directory where
 290 you've unpacked the sources and run this command for MinGW:
 291 </p>
 292 <pre class="code">
 293 mingw32-make
 294 </pre>
 295 <p>
 296 Or this command for Cygwin:
 297 </p>
 298 <pre class="code">
 299 make
 300 </pre>
 301 <p>
 302 Then follow the installation instructions below.
 303 </p>
 304 <h3>Installing LuaJIT</h3>
 305 <p>
 306 Copy <tt>luajit.exe</tt> and <tt>lua51.dll</tt> (built in the <tt>src</tt>
 307 directory) to a newly created directory (any location is ok).
 308 Add <tt>lua</tt> and <tt>lua\jit</tt> directories below it and copy
 309 all Lua files from the <tt>lib</tt> directory of the distribution
 310 to the latter directory.
 311 </p>
 312 <p>
 313 There are no hardcoded
 314 absolute path names &mdash; all modules are loaded relative to the
 315 directory where <tt>luajit.exe</tt> is installed
 316 (see <tt>src/luaconf.h</tt>).
 317 </p>
 318
 319 <h2 id="cross">Cross-compiling LuaJIT</h2>
 320 <p>
 321 The build system has limited support for cross-compilation. For details
 322 check the comments in <tt>src/Makefile</tt>. Here are some popular examples:
 323 </p>
 324 <p>
 325 You can cross-compile to a 32 bit binary on a multilib x64 OS by
 326 installing the multilib development packages (e.g. <tt>libc6-dev-i386</tt>
 327 on Debian/Ubuntu) and running:
 328 </p>
 329 <pre class="code">
 330 make CC="gcc -m32"
 331 </pre>
 332 <p>
 333 You can cross-compile for a Windows target on Debian/Ubuntu by
 334 installing the <tt>mingw32</tt> package and running:
 335 </p>
 336 <pre class="code">
 337 make HOST_CC="gcc -m32" CROSS=i586-mingw32msvc- TARGET_SYS=Windows
 338 </pre>
 339 <p>
 340 You can cross-compile for a PPC/e500v2 target on an x86 or x64 host system
 341 using a standard GNU cross-compile toolchain (Binutils, GCC, EGLIBC).
 342 The <tt>CROSS</tt> prefix may vary depending on the <tt>--target</tt>
 343 of the toolchain:
 344 </p>
 345 <pre class="code">
 346 make HOST_CC="gcc -m32" CROSS=powerpc-e500v2-linux-gnuspe- TARGET=ppcspe
 347 </pre>
 348
 349 <h2 id="embed">Embedding LuaJIT</h2>
 350 <p>
 351 LuaJIT is API-compatible with Lua 5.1. If you've already embedded Lua
 352 into your application, you probably don't need to do anything to switch
 353 to LuaJIT, except link with a different library:
 354 </p>
 355 <ul>
 356 <li>It's strongly suggested to build LuaJIT separately using the supplied
 357 build system. Please do <em>not</em> attempt to integrate the individual
 358 source files into your build tree. You'll most likely get the internal build
 359 dependencies wrong or mess up the compiler flags. Treat LuaJIT like any
 360 other external library and link your application with either the dynamic
 361 or static library, depending on your needs.</li>
 362 <li>If you want to load C modules compiled for plain Lua
 363 with <tt>require()</tt>, you need to make sure the public symbols
 364 (e.g. <tt>lua_pushnumber</tt>) are exported, too:
 365 <ul><li>On POSIX systems you can either link to the shared library
 366 or link the static library into your application. In the latter case
 367 you'll need to export all public symbols from your main executable
 368 (e.g. <tt>-Wl,-E</tt> on Linux) and add the external dependencies
 369 (e.g. <tt>-lm -ldl</tt> on Linux).</li>
 370 <li>Since Windows symbols are bound to a specific DLL name, you need to
 371 link to the <tt>lua51.dll</tt> created by the LuaJIT build (do not rename
 372 the DLL). You may link LuaJIT statically on Windows only if you don't
 373 intend to load Lua/C modules at runtime.
 374 </li></ul>
 375 </li>
 376 <li>
 377 If you're building a 64 bit application on OSX which links directly or
 378 indirectly against LuaJIT, you need to link your main executable
 379 with these flags:
 380 <pre class="code">
 381 -pagezero_size 10000 -image_base 100000000
 382 </pre>
 383 Also, it's recommended to <tt>rebase</tt> all (self-compiled) shared libraries
 384 which are loaded at runtime on OSX/x64 (e.g. C extension modules for Lua).
 385 See: <tt>man rebase</tt>
 386 </li>
 387 </ul>
 388 <p>Additional hints for initializing LuaJIT using the C API functions:</p>
 389 <ul>
 390 <li>Here's a
 391 <a href="http://lua-users.org/wiki/SimpleLuaApiExample"><span class="ext">&raquo;</span>&nbsp;simple example</a>
 392 for embedding Lua or LuaJIT into your application.</li>
 393 <li>Make sure you use <tt>luaL_newstate</tt>. Avoid using
 394 <tt>lua_newstate</tt>, since this uses the (slower) default memory
 395 allocator from your system (no support for this on x64).</tt></li>
 396 <li>Make sure you use <tt>luaL_openlibs</tt> and not the old Lua 5.0 style
 397 of calling <tt>luaopen_base</tt> etc. directly.</li>
 398 <li>To change or extend the list of standard libraries to load, copy
 399 <tt>src/lib_init.c</tt> to your project and modify it accordingly.
 400 Make sure the <tt>jit</tt> library is loaded or the JIT compiler
 401 will not be activated.</li>
 402 <li>The <tt>bit.*</tt> module for bitwise operations
 403 is already built-in. There's no need to statically link
 404 <a href="http://bitop.luajit.org/"><span class="ext">&raquo;</span>&nbsp;Lua BitOp</a> to your application.</li>
 405 </ul>
 406
 407 <h2 id="distro">Hints for Distribution Maintainers</h2>
 408 <p>
 409 The LuaJIT build system has extra provisions for the needs of most
 410 POSIX-based distributions. If you're a package maintainer for
 411 a distribution, <em>please</em> make use of these features and
 412 avoid patching, subverting, autotoolizing or messing up the build system
 413 in unspeakable ways.
 414 </p>
 415 <p>
 416 There should be absolutely no need to patch <tt>luaconf.h</tt> or any
 417 of the Makefiles. And please do not hand-pick files for your packages &mdash;
 418 simply use whatever <tt>make install</tt> creates. There's a reason
 419 for all of the files <em>and</em> directories it creates.
 420 </p>
 421 <p>
 422 The build system uses GNU make and autodetects most settings based on
 423 the host you're building it on. This should work fine for native builds,
 424 even when sandboxed. You may need to pass some of the following flags to
 425 <em>both</em> the <tt>make</tt> and the <tt>make install</tt> command lines
 426 for a regular distribution build:
 427 </p>
 428 <ul>
 429 <li><tt>PREFIX</tt> overrides the installation path and should usually
 430 be set to <tt>/usr</tt>. Setting this also changes the module paths and
 431 the <tt>-rpath</tt> of the shared library.</li>
 432 <li><tt>DESTDIR</tt> is an absolute path which allows you to install
 433 to a shadow tree instead of the root tree of the build system.</li>
 434 <li>Have a look at the top-level <tt>Makefile</tt> and <tt>src/Makefile</tt>
 435 for additional variables to tweak. The following variables <em>may</em> be
 436 overriden, but it's <em>not</em> recommended, except for special needs
 437 like cross-builds:
 438 <tt>BUILDMODE, CC, HOST_CC, STATIC_CC, DYNAMIC_CC, CFLAGS, HOST_CFLAGS,
 439 TARGET_CFLAGS, LDFLAGS, HOST_LDFLAGS, TARGET_LDFLAGS, TARGET_SHLDFLAGS,
 440 LIBS, HOST_LIBS, TARGET_LIBS, CROSS, HOST_SYS, TARGET_SYS</tt></li>
 441 </ul>
 442 <p>
 443 The build system has a special target for an amalgamated build, i.e.
 444 <tt>make amalg</tt>. This compiles the LuaJIT core as one huge C file
 445 and allows GCC to generate faster and shorter code. Alas, this requires
 446 lots of memory during the build. This may be a problem for some users,
 447 that's why it's not enabled by default. But it shouldn't be a problem for
 448 most build farms. It's recommended that binary distributions use this
 449 target for their LuaJIT builds.
 450 </p>
 451 <p>
 452 The tl;dr version of the above:
 453 </p>
 454 <pre class="code">
 455 make amalg PREFIX=/usr && \
 456 make install PREFIX=/usr DESTDIR=/tmp/buildroot
 457 </pre>
 458 <p>
 459 Finally, if you encounter any difficulties, please
 460 <a href="contact.html">contact me</a> first, instead of releasing a broken
 461 package onto unsuspecting users. Because they'll usually gonna complain
 462 to me (the upstream) and not you (the package maintainer), anyway.
 463 </p>
 464 <br class="flush">
 465 </div>
 466 <div id="foot">
 467 <hr class="hide">
 468 Copyright &copy; 2005-2011 Mike Pall
 469 <span class="noprint">
 470 &middot;
 471 <a href="contact.html">Contact</a>
 472 </span>
 473 </div>
 474 </body>
 475 </html>