install.html (25008B)
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-2016, 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 font-size: 80%; 15 } 16 table.compat td { 17 border: 1px solid #bfcfff; 18 height: 2.5em; 19 } 20 table.compat tr.compathead td { 21 font-weight: bold; 22 border-bottom: 2px solid #bfcfff; 23 } 24 tr.compathead td.compatos { 25 vertical-align: top; 26 } 27 table.compat td.compatcpu { 28 width: 18%; 29 border-right: 2px solid #bfcfff; 30 } 31 td.compatos { 32 width: 21%; 33 vertical-align: middle; 34 } 35 td.compatno { 36 background-color: #d0d0d0; 37 } 38 </style> 39 </head> 40 <body> 41 <div id="site"> 42 <a href="http://luajit.org"><span>Lua<span id="logo">JIT</span></span></a> 43 </div> 44 <div id="head"> 45 <h1>Installation</h1> 46 </div> 47 <div id="nav"> 48 <ul><li> 49 <a href="luajit.html">LuaJIT</a> 50 <ul><li> 51 <a href="http://luajit.org/download.html">Download <span class="ext">»</span></a> 52 </li><li> 53 <a class="current" href="install.html">Installation</a> 54 </li><li> 55 <a href="running.html">Running</a> 56 </li></ul> 57 </li><li> 58 <a href="extensions.html">Extensions</a> 59 <ul><li> 60 <a href="ext_ffi.html">FFI Library</a> 61 <ul><li> 62 <a href="ext_ffi_tutorial.html">FFI Tutorial</a> 63 </li><li> 64 <a href="ext_ffi_api.html">ffi.* API</a> 65 </li><li> 66 <a href="ext_ffi_semantics.html">FFI Semantics</a> 67 </li></ul> 68 </li><li> 69 <a href="ext_jit.html">jit.* Library</a> 70 </li><li> 71 <a href="ext_c_api.html">Lua/C API</a> 72 </li><li> 73 <a href="ext_profiler.html">Profiler</a> 74 </li></ul> 75 </li><li> 76 <a href="status.html">Status</a> 77 <ul><li> 78 <a href="changes.html">Changes</a> 79 </li></ul> 80 </li><li> 81 <a href="faq.html">FAQ</a> 82 </li><li> 83 <a href="http://luajit.org/performance.html">Performance <span class="ext">»</span></a> 84 </li><li> 85 <a href="http://wiki.luajit.org/">Wiki <span class="ext">»</span></a> 86 </li><li> 87 <a href="http://luajit.org/list.html">Mailing List <span class="ext">»</span></a> 88 </li></ul> 89 </div> 90 <div id="main"> 91 <p> 92 LuaJIT is only distributed as a source package. This page explains 93 how to build and install LuaJIT with different operating systems 94 and C compilers. 95 </p> 96 <p> 97 For the impatient (on POSIX systems): 98 </p> 99 <pre class="code"> 100 make && sudo make install 101 </pre> 102 <p> 103 LuaJIT currently builds out-of-the box on most systems. 104 Here's the compatibility matrix for the supported combinations of 105 operating systems, CPUs and compilers: 106 </p> 107 <table class="compat"> 108 <tr class="compathead"> 109 <td class="compatcpu">CPU / OS</td> 110 <td class="compatos"><a href="#posix">Linux</a> or<br><a href="#android">Android</a></td> 111 <td class="compatos"><a href="#posix">*BSD, Other</a></td> 112 <td class="compatos"><a href="#posix">OSX 10.4+</a> or<br><a href="#ios">iOS 3.0+</a></td> 113 <td class="compatos"><a href="#windows">Windows<br>XP/Vista/7</a></td> 114 </tr> 115 <tr class="odd separate"> 116 <td class="compatcpu">x86 (32 bit)</td> 117 <td class="compatos">GCC 4.2+</td> 118 <td class="compatos">GCC 4.2+</td> 119 <td class="compatos">XCode 5.0+<br>Clang</td> 120 <td class="compatos">MSVC, MSVC/EE<br>WinSDK<br>MinGW, Cygwin</td> 121 </tr> 122 <tr class="even"> 123 <td class="compatcpu">x64 (64 bit)</td> 124 <td class="compatos">GCC 4.2+</td> 125 <td class="compatos">GCC 4.2+<br>ORBIS (<a href="#ps4">PS4</a>)</td> 126 <td class="compatos">XCode 5.0+<br>Clang</td> 127 <td class="compatos">MSVC + SDK v7.0<br>WinSDK v7.0<br>Durango (<a href="#xboxone">Xbox One</a>)</td> 128 </tr> 129 <tr class="odd"> 130 <td class="compatcpu"><a href="#cross2">ARMv5+<br>ARM9E+</a></td> 131 <td class="compatos">GCC 4.2+</td> 132 <td class="compatos">GCC 4.2+<br>PSP2 (<a href="#psvita">PS VITA</a>)</td> 133 <td class="compatos">XCode 5.0+<br>Clang</td> 134 <td class="compatos compatno"> </td> 135 </tr> 136 <tr class="even"> 137 <td class="compatcpu"><a href="#cross2">ARM64</a></td> 138 <td class="compatos">GCC 4.8+</td> 139 <td class="compatos compatno"> </td> 140 <td class="compatos">XCode 6.0+<br>Clang 3.5+</td> 141 <td class="compatos compatno"> </td> 142 </tr> 143 <tr class="odd"> 144 <td class="compatcpu"><a href="#cross2">PPC</a></td> 145 <td class="compatos">GCC 4.3+</td> 146 <td class="compatos">GCC 4.3+<br>GCC 4.1 (<a href="#ps3">PS3</a>)</td> 147 <td class="compatos compatno"> </td> 148 <td class="compatos">XEDK (<a href="#xbox360">Xbox 360</a>)</td> 149 </tr> 150 <tr class="even"> 151 <td class="compatcpu"><a href="#cross2">MIPS32<br>MIPS64</a></td> 152 <td class="compatos">GCC 4.3+</td> 153 <td class="compatos">GCC 4.3+</td> 154 <td class="compatos compatno"> </td> 155 <td class="compatos compatno"> </td> 156 </tr> 157 </table> 158 159 <h2>Configuring LuaJIT</h2> 160 <p> 161 The standard configuration should work fine for most installations. 162 Usually there is no need to tweak the settings. The following files 163 hold all user-configurable settings: 164 </p> 165 <ul> 166 <li><tt>src/luaconf.h</tt> sets some configuration variables.</li> 167 <li><tt>Makefile</tt> has settings for <b>installing</b> LuaJIT (POSIX 168 only).</li> 169 <li><tt>src/Makefile</tt> has settings for <b>compiling</b> LuaJIT 170 under POSIX, MinGW or Cygwin.</li> 171 <li><tt>src/msvcbuild.bat</tt> has settings for compiling LuaJIT with 172 MSVC or WinSDK.</li> 173 </ul> 174 <p> 175 Please read the instructions given in these files, before changing 176 any settings. 177 </p> 178 179 <h2 id="posix">POSIX Systems (Linux, OSX, *BSD etc.)</h2> 180 <h3>Prerequisites</h3> 181 <p> 182 Depending on your distribution, you may need to install a package for 183 GCC, the development headers and/or a complete SDK. E.g. on a current 184 Debian/Ubuntu, install <tt>libc6-dev</tt> with the package manager. 185 </p> 186 <p> 187 Download the current source package of LuaJIT (pick the .tar.gz), 188 if you haven't already done so. Move it to a directory of your choice, 189 open a terminal window and change to this directory. Now unpack the archive 190 and change to the newly created directory: 191 </p> 192 <pre class="code"> 193 tar zxf LuaJIT-2.0.4.tar.gz 194 cd LuaJIT-2.0.4</pre> 195 <h3>Building LuaJIT</h3> 196 <p> 197 The supplied Makefiles try to auto-detect the settings needed for your 198 operating system and your compiler. They need to be run with GNU Make, 199 which is probably the default on your system, anyway. Simply run: 200 </p> 201 <pre class="code"> 202 make 203 </pre> 204 <p> 205 This always builds a native binary, depending on the host OS 206 you're running this command on. Check the section on 207 <a href="#cross">cross-compilation</a> for more options. 208 </p> 209 <p> 210 By default, modules are only searched under the prefix <tt>/usr/local</tt>. 211 You can add an extra prefix to the search paths by appending the 212 <tt>PREFIX</tt> option, e.g.: 213 </p> 214 <pre class="code"> 215 make PREFIX=/home/myself/lj2 216 </pre> 217 <p> 218 Note for OSX: if the <tt>MACOSX_DEPLOYMENT_TARGET</tt> environment 219 variable is not set, then it's forced to <tt>10.4</tt>. 220 </p> 221 <h3>Installing LuaJIT</h3> 222 <p> 223 The top-level Makefile installs LuaJIT by default under 224 <tt>/usr/local</tt>, i.e. the executable ends up in 225 <tt>/usr/local/bin</tt> and so on. You need root privileges 226 to write to this path. So, assuming sudo is installed on your system, 227 run the following command and enter your sudo password: 228 </p> 229 <pre class="code"> 230 sudo make install 231 </pre> 232 <p> 233 Otherwise specify the directory prefix as an absolute path, e.g.: 234 </p> 235 <pre class="code"> 236 make install PREFIX=/home/myself/lj2 237 </pre> 238 <p> 239 Obviously the prefixes given during build and installation need to be the same. 240 </p> 241 242 <h2 id="windows">Windows Systems</h2> 243 <h3>Prerequisites</h3> 244 <p> 245 Either install one of the open source SDKs 246 (<a href="http://mingw.org/"><span class="ext">»</span> MinGW</a> or 247 <a href="http://www.cygwin.com/"><span class="ext">»</span> Cygwin</a>), which come with a modified 248 GCC plus the required development headers. 249 </p> 250 <p> 251 Or install Microsoft's Visual C++ (MSVC). The freely downloadable 252 <a href="http://www.microsoft.com/Express/VC/"><span class="ext">»</span> Express Edition</a> 253 works just fine, but only contains an x86 compiler. 254 </p> 255 <p> 256 The freely downloadable 257 <a href="http://msdn.microsoft.com/en-us/windowsserver/bb980924.aspx"><span class="ext">»</span> Windows SDK</a> 258 only comes with command line tools, but this is all you need to build LuaJIT. 259 It contains x86 and x64 compilers. 260 </p> 261 <p> 262 Next, download the source package and unpack it using an archive manager 263 (e.g. the Windows Explorer) to a directory of your choice. 264 </p> 265 <h3>Building with MSVC</h3> 266 <p> 267 Open a "Visual Studio .NET Command Prompt", <tt>cd</tt> to the 268 directory where you've unpacked the sources and run these commands: 269 </p> 270 <pre class="code"> 271 cd src 272 msvcbuild 273 </pre> 274 <p> 275 Then follow the installation instructions below. 276 </p> 277 <h3>Building with the Windows SDK</h3> 278 <p> 279 Open a "Windows SDK Command Shell" and select the x86 compiler: 280 </p> 281 <pre class="code"> 282 setenv /release /x86 283 </pre> 284 <p> 285 Or select the x64 compiler: 286 </p> 287 <pre class="code"> 288 setenv /release /x64 289 </pre> 290 <p> 291 Then <tt>cd</tt> to the directory where you've unpacked the sources 292 and run these commands: 293 </p> 294 <pre class="code"> 295 cd src 296 msvcbuild 297 </pre> 298 <p> 299 Then follow the installation instructions below. 300 </p> 301 <h3>Building with MinGW or Cygwin</h3> 302 <p> 303 Open a command prompt window and make sure the MinGW or Cygwin programs 304 are in your path. Then <tt>cd</tt> to the directory where 305 you've unpacked the sources and run this command for MinGW: 306 </p> 307 <pre class="code"> 308 mingw32-make 309 </pre> 310 <p> 311 Or this command for Cygwin: 312 </p> 313 <pre class="code"> 314 make 315 </pre> 316 <p> 317 Then follow the installation instructions below. 318 </p> 319 <h3>Installing LuaJIT</h3> 320 <p> 321 Copy <tt>luajit.exe</tt> and <tt>lua51.dll</tt> (built in the <tt>src</tt> 322 directory) to a newly created directory (any location is ok). 323 Add <tt>lua</tt> and <tt>lua\jit</tt> directories below it and copy 324 all Lua files from the <tt>src\jit</tt> directory of the distribution 325 to the latter directory. 326 </p> 327 <p> 328 There are no hardcoded 329 absolute path names — all modules are loaded relative to the 330 directory where <tt>luajit.exe</tt> is installed 331 (see <tt>src/luaconf.h</tt>). 332 </p> 333 334 <h2 id="cross">Cross-compiling LuaJIT</h2> 335 <p> 336 First, let's clear up some terminology: 337 </p> 338 <ul> 339 <li>Host: This is your development system, usually based on a x64 or x86 CPU.</li> 340 <li>Target: This is the target system you want LuaJIT to run on, e.g. Android/ARM.</li> 341 <li>Toolchain: This comprises a C compiler, linker, assembler and a matching C library.</li> 342 <li>Host (or system) toolchain: This is the toolchain used to build native binaries for your host system.</li> 343 <li>Cross-compile toolchain: This is the toolchain used to build binaries for the target system. They can only be run on the target system.</li> 344 </ul> 345 <p> 346 The GNU Makefile-based build system allows cross-compiling on any host 347 for any supported target: 348 </p> 349 <ul> 350 <li>Yes, you need a toolchain for both your host <em>and</em> your target!</li> 351 <li>Both host and target architectures must have the same pointer size.</li> 352 <li>E.g. if you want to cross-compile to a 32 bit target on a 64 bit host, you need to install the multilib development package (e.g. <tt>libc6-dev-i386</tt> on Debian/Ubuntu) and build a 32 bit host part (<tt>HOST_CC="gcc -m32"</tt>).</li> 353 <li>64 bit targets always require compilation on a 64 bit host.</li> 354 </ul> 355 <p> 356 You need to specify <tt>TARGET_SYS</tt> whenever the host OS and the 357 target OS differ, or you'll get assembler or linker errors: 358 </p> 359 <ul> 360 <li>E.g. if you're compiling on a Windows or OSX host for embedded Linux or Android, you need to add <tt>TARGET_SYS=Linux</tt> to the examples below.</li> 361 <li>For a minimal target OS, you may need to disable the built-in allocator in <tt>src/Makefile</tt> and use <tt>TARGET_SYS=Other</tt>.</li> 362 <li>Don't forget to specify the same <tt>TARGET_SYS</tt> for the install step, too.</li> 363 </ul> 364 <p> 365 Here are some examples where host and target have the same CPU: 366 </p> 367 <pre class="code"> 368 # Cross-compile to a 32 bit binary on a multilib x64 OS 369 make CC="gcc -m32" 370 371 # Cross-compile on Debian/Ubuntu for Windows (mingw32 package) 372 make HOST_CC="gcc -m32" CROSS=i586-mingw32msvc- TARGET_SYS=Windows 373 </pre> 374 <p id="cross2"> 375 The <tt>CROSS</tt> prefix allows specifying a standard GNU cross-compile 376 toolchain (Binutils, GCC and a matching libc). The prefix may vary 377 depending on the <tt>--target</tt> the toolchain was built for (note the 378 <tt>CROSS</tt> prefix has a trailing <tt>"-"</tt>). The examples below 379 use the canonical toolchain triplets for Linux. 380 </p> 381 <p> 382 Since there's often no easy way to detect CPU features at runtime, it's 383 important to compile with the proper CPU or architecture settings: 384 </o> 385 <ul> 386 <li>The best way to get consistent results is to specify the correct settings when building the toolchain yourself.</li> 387 <li>For a pre-built, generic toolchain add <tt>-mcpu=...</tt> or <tt>-march=...</tt> and other necessary flags to <tt>TARGET_CFLAGS</tt>.</li> 388 <li>For ARM it's important to have the correct <tt>-mfloat-abi=...</tt> setting, too. Otherwise LuaJIT may not run at the full performance of your target CPU.</li> 389 <li>For MIPS it's important to select a supported ABI (o32 on MIPS32, n64 on MIPS64) and consistently compile your project either with hard-float or soft-float compiler settings.</li> 390 </ul> 391 <p> 392 Here are some examples for targets with a different CPU than the host: 393 </p> 394 <pre class="code"> 395 # ARM soft-float 396 make HOST_CC="gcc -m32" CROSS=arm-linux-gnueabi- \ 397 TARGET_CFLAGS="-mfloat-abi=soft" 398 399 # ARM soft-float ABI with VFP (example for Cortex-A9) 400 make HOST_CC="gcc -m32" CROSS=arm-linux-gnueabi- \ 401 TARGET_CFLAGS="-mcpu=cortex-a9 -mfloat-abi=softfp" 402 403 # ARM hard-float ABI with VFP (armhf, most modern toolchains) 404 make HOST_CC="gcc -m32" CROSS=arm-linux-gnueabihf- 405 406 # ARM64 407 make CROSS=aarch64-linux- 408 409 # PPC 410 make HOST_CC="gcc -m32" CROSS=powerpc-linux-gnu- 411 412 # MIPS32 big-endian 413 make HOST_CC="gcc -m32" CROSS=mips-linux- 414 # MIPS32 little-endian 415 make HOST_CC="gcc -m32" CROSS=mipsel-linux- 416 417 # MIPS64 big-endian 418 make CROSS=mips-linux- TARGET_CFLAGS="-mips64r2 -mabi=64" 419 # MIPS64 little-endian 420 make CROSS=mipsel-linux- TARGET_CFLAGS="-mips64r2 -mabi=64" 421 </pre> 422 <p> 423 You can cross-compile for <b id="android">Android</b> using the <a href="https://developer.android.com/ndk/index.html">Android NDK</a>. 424 The environment variables need to match the install locations and the 425 desired target platform. E.g. Android 4.0 corresponds to ABI level 14. 426 For details check the folder <tt>docs</tt> in the NDK directory. 427 </p> 428 <p> 429 Only a few common variations for the different CPUs, ABIs and platforms 430 are listed. Please use your own judgement for which combination you want 431 to build/deploy or which lowest common denominator you want to pick: 432 </p> 433 <pre class="code"> 434 # Android/ARM, armeabi (ARMv5TE soft-float), Android 2.2+ (Froyo) 435 NDK=/opt/android/ndk 436 NDKABI=8 437 NDKVER=$NDK/toolchains/arm-linux-androideabi-4.9 438 NDKP=$NDKVER/prebuilt/linux-x86/bin/arm-linux-androideabi- 439 NDKF="--sysroot $NDK/platforms/android-$NDKABI/arch-arm" 440 make HOST_CC="gcc -m32" CROSS=$NDKP TARGET_FLAGS="$NDKF" 441 442 # Android/ARM, armeabi-v7a (ARMv7 VFP), Android 4.0+ (ICS) 443 NDK=/opt/android/ndk 444 NDKABI=14 445 NDKVER=$NDK/toolchains/arm-linux-androideabi-4.9 446 NDKP=$NDKVER/prebuilt/linux-x86/bin/arm-linux-androideabi- 447 NDKF="--sysroot $NDK/platforms/android-$NDKABI/arch-arm" 448 NDKARCH="-march=armv7-a -mfloat-abi=softfp -Wl,--fix-cortex-a8" 449 make HOST_CC="gcc -m32" CROSS=$NDKP TARGET_FLAGS="$NDKF $NDKARCH" 450 451 # Android/MIPS, mipsel (MIPS32R1 hard-float), Android 4.0+ (ICS) 452 NDK=/opt/android/ndk 453 NDKABI=14 454 NDKVER=$NDK/toolchains/mipsel-linux-android-4.9 455 NDKP=$NDKVER/prebuilt/linux-x86/bin/mipsel-linux-android- 456 NDKF="--sysroot $NDK/platforms/android-$NDKABI/arch-mips" 457 make HOST_CC="gcc -m32" CROSS=$NDKP TARGET_FLAGS="$NDKF" 458 459 # Android/x86, x86 (i686 SSE3), Android 4.0+ (ICS) 460 NDK=/opt/android/ndk 461 NDKABI=14 462 NDKVER=$NDK/toolchains/x86-4.9 463 NDKP=$NDKVER/prebuilt/linux-x86/bin/i686-linux-android- 464 NDKF="--sysroot $NDK/platforms/android-$NDKABI/arch-x86" 465 make HOST_CC="gcc -m32" CROSS=$NDKP TARGET_FLAGS="$NDKF" 466 </pre> 467 <p> 468 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">»</span> iOS SDK</a>: 469 </p> 470 <p style="font-size: 8pt;"> 471 Note: <b>the JIT compiler is disabled for iOS</b>, because regular iOS Apps 472 are not allowed to generate code at runtime. You'll only get the performance 473 of the LuaJIT interpreter on iOS. This is still faster than plain Lua, but 474 much slower than the JIT compiler. Please complain to Apple, not me. 475 Or use Android. :-p 476 </p> 477 <pre class="code"> 478 # iOS/ARM (32 bit) 479 ISDKP=$(xcrun --sdk iphoneos --show-sdk-path) 480 ICC=$(xcrun --sdk iphoneos --find clang) 481 ISDKF="-arch armv7 -isysroot $ISDKP" 482 make HOST_CC="clang -m32 -arch i386" CROSS="$(dirname $ICC)/" \ 483 TARGET_FLAGS="$ISDKF" TARGET_SYS=iOS 484 485 # iOS/ARM64 486 ISDKP=$(xcrun --sdk iphoneos --show-sdk-path) 487 ICC=$(xcrun --sdk iphoneos --find clang) 488 ISDKF="-arch arm64 -isysroot $ISDKP" 489 make CROSS="$(dirname $ICC)/" TARGET_FLAGS="$ISDKF" TARGET_SYS=iOS 490 </pre> 491 492 <h3 id="consoles">Cross-compiling for consoles</h3> 493 <p> 494 Building LuaJIT for consoles requires both a supported host compiler 495 (x86 or x64) and a cross-compiler (to PPC or ARM) from the official 496 console SDK. 497 </p> 498 <p> 499 Due to restrictions on consoles, the JIT compiler is disabled and only 500 the fast interpreter is built. This is still faster than plain Lua, 501 but much slower than the JIT compiler. The FFI is disabled, too, since 502 it's not very useful in such an environment. 503 </p> 504 <p> 505 The following commands build a static library <tt>libluajit.a</tt>, 506 which can be linked against your game, just like the Lua library. 507 </p> 508 <p> 509 To cross-compile for <b id="ps3">PS3</b> from a Linux host (requires 510 32 bit GCC, i.e. multilib Linux/x64) or a Windows host (requires 511 32 bit MinGW), run this command: 512 </p> 513 <pre class="code"> 514 make HOST_CC="gcc -m32" CROSS=ppu-lv2- 515 </pre> 516 <p> 517 To cross-compile for <b id="ps4">PS4</b> from a Windows host, 518 open a "Visual Studio .NET Command Prompt" (64 bit host compiler), 519 <tt>cd</tt> to the directory where you've unpacked the sources and 520 run the following commands: 521 </p> 522 <pre class="code"> 523 cd src 524 ps4build 525 </pre> 526 <p> 527 To cross-compile for <b id="psvita">PS Vita</b> from a Windows host, 528 open a "Visual Studio .NET Command Prompt" (32 bit host compiler), 529 <tt>cd</tt> to the directory where you've unpacked the sources and 530 run the following commands: 531 </p> 532 <pre class="code"> 533 cd src 534 psvitabuild 535 </pre> 536 <p> 537 To cross-compile for <b id="xbox360">Xbox 360</b> from a Windows host, 538 open a "Visual Studio .NET Command Prompt" (32 bit host compiler), 539 <tt>cd</tt> to the directory where you've unpacked the sources and run 540 the following commands: 541 </p> 542 <pre class="code"> 543 cd src 544 xedkbuild 545 </pre> 546 <p> 547 To cross-compile for <b id="xboxone">Xbox One</b> from a Windows host, 548 open a "Visual Studio .NET Command Prompt" (64 bit host compiler), 549 <tt>cd</tt> to the directory where you've unpacked the sources and run 550 the following commands: 551 </p> 552 <pre class="code"> 553 cd src 554 xb1build 555 </pre> 556 557 <h2 id="embed">Embedding LuaJIT</h2> 558 <p> 559 LuaJIT is API-compatible with Lua 5.1. If you've already embedded Lua 560 into your application, you probably don't need to do anything to switch 561 to LuaJIT, except link with a different library: 562 </p> 563 <ul> 564 <li>It's strongly suggested to build LuaJIT separately using the supplied 565 build system. Please do <em>not</em> attempt to integrate the individual 566 source files into your build tree. You'll most likely get the internal build 567 dependencies wrong or mess up the compiler flags. Treat LuaJIT like any 568 other external library and link your application with either the dynamic 569 or static library, depending on your needs.</li> 570 <li>If you want to load C modules compiled for plain Lua 571 with <tt>require()</tt>, you need to make sure the public symbols 572 (e.g. <tt>lua_pushnumber</tt>) are exported, too: 573 <ul><li>On POSIX systems you can either link to the shared library 574 or link the static library into your application. In the latter case 575 you'll need to export all public symbols from your main executable 576 (e.g. <tt>-Wl,-E</tt> on Linux) and add the external dependencies 577 (e.g. <tt>-lm -ldl</tt> on Linux).</li> 578 <li>Since Windows symbols are bound to a specific DLL name, you need to 579 link to the <tt>lua51.dll</tt> created by the LuaJIT build (do not rename 580 the DLL). You may link LuaJIT statically on Windows only if you don't 581 intend to load Lua/C modules at runtime. 582 </li></ul> 583 </li> 584 <li> 585 If you're building a 64 bit application on OSX which links directly or 586 indirectly against LuaJIT, you need to link your main executable 587 with these flags: 588 <pre class="code"> 589 -pagezero_size 10000 -image_base 100000000 590 </pre> 591 Also, it's recommended to <tt>rebase</tt> all (self-compiled) shared libraries 592 which are loaded at runtime on OSX/x64 (e.g. C extension modules for Lua). 593 See: <tt>man rebase</tt> 594 </li> 595 </ul> 596 <p>Additional hints for initializing LuaJIT using the C API functions:</p> 597 <ul> 598 <li>Here's a 599 <a href="http://lua-users.org/wiki/SimpleLuaApiExample"><span class="ext">»</span> simple example</a> 600 for embedding Lua or LuaJIT into your application.</li> 601 <li>Make sure you use <tt>luaL_newstate</tt>. Avoid using 602 <tt>lua_newstate</tt>, since this uses the (slower) default memory 603 allocator from your system (no support for this on x64).</li> 604 <li>Make sure you use <tt>luaL_openlibs</tt> and not the old Lua 5.0 style 605 of calling <tt>luaopen_base</tt> etc. directly.</li> 606 <li>To change or extend the list of standard libraries to load, copy 607 <tt>src/lib_init.c</tt> to your project and modify it accordingly. 608 Make sure the <tt>jit</tt> library is loaded or the JIT compiler 609 will not be activated.</li> 610 <li>The <tt>bit.*</tt> module for bitwise operations 611 is already built-in. There's no need to statically link 612 <a href="http://bitop.luajit.org/"><span class="ext">»</span> Lua BitOp</a> to your application.</li> 613 </ul> 614 615 <h2 id="distro">Hints for Distribution Maintainers</h2> 616 <p> 617 The LuaJIT build system has extra provisions for the needs of most 618 POSIX-based distributions. If you're a package maintainer for 619 a distribution, <em>please</em> make use of these features and 620 avoid patching, subverting, autotoolizing or messing up the build system 621 in unspeakable ways. 622 </p> 623 <p> 624 There should be absolutely no need to patch <tt>luaconf.h</tt> or any 625 of the Makefiles. And please do not hand-pick files for your packages — 626 simply use whatever <tt>make install</tt> creates. There's a reason 627 for all of the files <em>and</em> directories it creates. 628 </p> 629 <p> 630 The build system uses GNU make and auto-detects most settings based on 631 the host you're building it on. This should work fine for native builds, 632 even when sandboxed. You may need to pass some of the following flags to 633 <em>both</em> the <tt>make</tt> and the <tt>make install</tt> command lines 634 for a regular distribution build: 635 </p> 636 <ul> 637 <li><tt>PREFIX</tt> overrides the installation path and should usually 638 be set to <tt>/usr</tt>. Setting this also changes the module paths and 639 the paths needed to locate the shared library.</li> 640 <li><tt>DESTDIR</tt> is an absolute path which allows you to install 641 to a shadow tree instead of the root tree of the build system.</li> 642 <li><tt>MULTILIB</tt> sets the architecture-specific library path component 643 for multilib systems. The default is <tt>lib</tt>.</li> 644 <li>Have a look at the top-level <tt>Makefile</tt> and <tt>src/Makefile</tt> 645 for additional variables to tweak. The following variables <em>may</em> be 646 overridden, but it's <em>not</em> recommended, except for special needs 647 like cross-builds: 648 <tt>BUILDMODE, CC, HOST_CC, STATIC_CC, DYNAMIC_CC, CFLAGS, HOST_CFLAGS, 649 TARGET_CFLAGS, LDFLAGS, HOST_LDFLAGS, TARGET_LDFLAGS, TARGET_SHLDFLAGS, 650 TARGET_FLAGS, LIBS, HOST_LIBS, TARGET_LIBS, CROSS, HOST_SYS, TARGET_SYS 651 </tt></li> 652 </ul> 653 <p> 654 The build system has a special target for an amalgamated build, i.e. 655 <tt>make amalg</tt>. This compiles the LuaJIT core as one huge C file 656 and allows GCC to generate faster and shorter code. Alas, this requires 657 lots of memory during the build. This may be a problem for some users, 658 that's why it's not enabled by default. But it shouldn't be a problem for 659 most build farms. It's recommended that binary distributions use this 660 target for their LuaJIT builds. 661 </p> 662 <p> 663 The tl;dr version of the above: 664 </p> 665 <pre class="code"> 666 make amalg PREFIX=/usr && \ 667 make install PREFIX=/usr DESTDIR=/tmp/buildroot 668 </pre> 669 <p> 670 Finally, if you encounter any difficulties, please 671 <a href="contact.html">contact me</a> first, instead of releasing a broken 672 package onto unsuspecting users. Because they'll usually gonna complain 673 to me (the upstream) and not you (the package maintainer), anyway. 674 </p> 675 <br class="flush"> 676 </div> 677 <div id="foot"> 678 <hr class="hide"> 679 Copyright © 2005-2016 Mike Pall 680 <span class="noprint"> 681 · 682 <a href="contact.html">Contact</a> 683 </span> 684 </div> 685 </body> 686 </html>