install.html 21 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587
  1. <!DOCTYPE html>
  2. <html>
  3. <head>
  4. <title>Installation</title>
  5. <meta charset="utf-8">
  6. <meta name="Copyright" content="Copyright (C) 2005-2025">
  7. <meta name="Language" content="en">
  8. <link rel="stylesheet" type="text/css" href="bluequad.css" media="screen">
  9. <link rel="stylesheet" type="text/css" href="bluequad-print.css" media="print">
  10. <style type="text/css">
  11. table.compat {
  12. line-height: 1.2;
  13. font-size: 80%;
  14. }
  15. table.compat td {
  16. border: 1px solid #bfcfff;
  17. height: 1.5em;
  18. }
  19. table.compat tr.compathead td {
  20. font-weight: bold;
  21. border-bottom: 2px solid #bfcfff;
  22. }
  23. td.compatname {
  24. width: 10%;
  25. }
  26. td.compatbits {
  27. width: 5%;
  28. }
  29. td.compatx {
  30. width: 21%;
  31. }
  32. </style>
  33. </head>
  34. <body>
  35. <div id="site">
  36. <a href="https://luajit.org"><span>Lua<span id="logo">JIT</span></span></a>
  37. </div>
  38. <div id="head">
  39. <h1>Installation</h1>
  40. </div>
  41. <div id="nav">
  42. <ul><li>
  43. <a href="luajit.html">LuaJIT</a>
  44. <ul><li>
  45. <a href="https://luajit.org/download.html">Download <span class="ext">&raquo;</span></a>
  46. </li><li>
  47. <a class="current" href="install.html">Installation</a>
  48. </li><li>
  49. <a href="running.html">Running</a>
  50. </li></ul>
  51. </li><li>
  52. <a href="extensions.html">Extensions</a>
  53. <ul><li>
  54. <a href="ext_ffi.html">FFI Library</a>
  55. <ul><li>
  56. <a href="ext_ffi_tutorial.html">FFI Tutorial</a>
  57. </li><li>
  58. <a href="ext_ffi_api.html">ffi.* API</a>
  59. </li><li>
  60. <a href="ext_ffi_semantics.html">FFI Semantics</a>
  61. </li></ul>
  62. </li><li>
  63. <a href="ext_buffer.html">String Buffers</a>
  64. </li><li>
  65. <a href="ext_jit.html">jit.* Library</a>
  66. </li><li>
  67. <a href="ext_c_api.html">Lua/C API</a>
  68. </li><li>
  69. <a href="ext_profiler.html">Profiler</a>
  70. </li></ul>
  71. </li><li>
  72. <a href="https://luajit.org/status.html">Status <span class="ext">&raquo;</span></a>
  73. </li><li>
  74. <a href="https://luajit.org/faq.html">FAQ <span class="ext">&raquo;</span></a>
  75. </li><li>
  76. <a href="https://luajit.org/list.html">Mailing List <span class="ext">&raquo;</span></a>
  77. </li></ul>
  78. </div>
  79. <div id="main">
  80. <p>
  81. LuaJIT is only distributed as source code &mdash; get it from the
  82. <a href="https://luajit.org/download.html"><span class="ext">&raquo;</span>&nbsp;git repository</a>. This page explains how to build
  83. and install the LuaJIT binary and library for different operating systems.
  84. </p>
  85. <p>
  86. For the impatient (on POSIX systems):
  87. </p>
  88. <pre class="code">
  89. make &amp;&amp; sudo make install
  90. </pre>
  91. <h2 id="req">Requirements</h2>
  92. <p>
  93. LuaJIT currently builds out-of-the box on most systems. Please check the
  94. supported operating systems and CPU architectures on the
  95. <a href="https://luajit.org/status.html"><span class="ext">&raquo;</span>&nbsp;status page</a>.
  96. </p>
  97. <p>
  98. Building LuaJIT requires a recent toolchain based on GCC, Clang/LLVM or
  99. MSVC++.
  100. </p>
  101. <p>
  102. The Makefile-based build system requires GNU Make and supports
  103. cross-builds.
  104. </p>
  105. <p>
  106. Batch files are provided for MSVC++ builds and console cross-builds.
  107. </p>
  108. <h2>Configuring LuaJIT</h2>
  109. <p>
  110. The standard configuration should work fine for most installations.
  111. Usually there is no need to tweak the settings. The following files
  112. hold all user-configurable settings:
  113. </p>
  114. <ul>
  115. <li><tt>Makefile</tt> has settings for <b>installing</b> LuaJIT (POSIX
  116. only).</li>
  117. <li><tt>src/Makefile</tt> has settings for <b>compiling</b> LuaJIT
  118. under POSIX or MinGW.</li>
  119. <li><tt>src/msvcbuild.bat</tt> has settings for compiling LuaJIT with
  120. MSVC (Visual Studio).</li>
  121. </ul>
  122. <p>
  123. Please read the instructions given in these files, before changing
  124. any settings.
  125. </p>
  126. <p>
  127. All LuaJIT 64 bit ports use 64 bit GC objects by default (<tt>LJ_GC64</tt>).
  128. For x64, you can select the old 32-on-64 bit mode by adding
  129. <tt>XCFLAGS=-DLUAJIT_DISABLE_GC64</tt> to the make command.
  130. Please check the note about the
  131. <a href="extensions.html#string_dump">bytecode format</a> differences, too.
  132. </p>
  133. <h2 id="posix">POSIX Systems (Linux, macOS, *BSD etc.)</h2>
  134. <h3>Prerequisites</h3>
  135. <p>
  136. Depending on your distribution, you may need to install a package for a
  137. compiler (GCC or Clang/LLVM), the development headers and/or a complete SDK.
  138. E.g. on a current Debian/Ubuntu, install <tt>build-essential</tt> with the
  139. package manager.
  140. </p>
  141. </pre>
  142. <h3>Building LuaJIT</h3>
  143. <p>
  144. The supplied Makefiles try to auto-detect the settings needed for your
  145. operating system and your compiler. They need to be run with GNU Make,
  146. which is probably the default on your system, anyway. Simply run:
  147. </p>
  148. <pre class="code">
  149. make
  150. </pre>
  151. <p>
  152. This always builds a native binary, depending on the host OS
  153. you're running this command on. Check the section on
  154. <a href="#cross">cross-compilation</a> for more options.
  155. </p>
  156. <p>
  157. By default, modules are only searched under the prefix <tt>/usr/local</tt>.
  158. You can add an extra prefix to the search paths by appending the
  159. <tt>PREFIX</tt> option, e.g.:
  160. </p>
  161. <pre class="code">
  162. make PREFIX=/home/myself/lj2
  163. </pre>
  164. <p>
  165. Note for macOS: you <b>must</b> set the <tt>MACOSX_DEPLOYMENT_TARGET</tt>
  166. environment variable to a value supported by your toolchain:
  167. </p>
  168. <pre class="code">
  169. MACOSX_DEPLOYMENT_TARGET=XX.YY make
  170. </pre>
  171. <h3>Installing LuaJIT</h3>
  172. <p>
  173. The top-level Makefile installs LuaJIT by default under
  174. <tt>/usr/local</tt>, i.e. the executable ends up in
  175. <tt>/usr/local/bin</tt> and so on. You need root privileges
  176. to write to this path. So, assuming sudo is installed on your system,
  177. run the following command and enter your sudo password:
  178. </p>
  179. <pre class="code">
  180. sudo make install
  181. </pre>
  182. <p>
  183. Otherwise specify the directory prefix as an absolute path, e.g.:
  184. </p>
  185. <pre class="code">
  186. make install PREFIX=/home/myself/lj2
  187. </pre>
  188. <p>
  189. Obviously the prefixes given during build and installation need to be the same.
  190. </p>
  191. <h2 id="windows">Windows Systems</h2>
  192. <h3>Prerequisites</h3>
  193. <p>
  194. Either install the open source SDK <a href="http://mingw.org/"><span class="ext">&raquo;</span>&nbsp;MinGW</a>,
  195. which comes with a modified GCC plus the required development headers.
  196. Or install Microsoft's Visual Studio (MSVC).
  197. </p>
  198. <h3>Building with MSVC</h3>
  199. <p>
  200. Open a "Visual Studio Command Prompt" (x86, x64 or ARM64), <tt>cd</tt> to the
  201. directory with the source code and run these commands:
  202. </p>
  203. <pre class="code">
  204. cd src
  205. msvcbuild
  206. </pre>
  207. <p>
  208. Check the <tt>msvcbuild.bat</tt> file for more options.
  209. Then follow the installation instructions below.
  210. </p>
  211. <p>
  212. For an x64 to ARM64 cross-build run this first: <tt>vcvarsall.bat x64_arm64</tt>
  213. </p>
  214. <h3>Building with MinGW</h3>
  215. <p>
  216. Open a command prompt window and make sure the MinGW programs
  217. are in your path. Then <tt>cd</tt> to the directory of the git repository.
  218. Then run this command for MinGW:
  219. </p>
  220. <pre class="code">
  221. mingw32-make
  222. </pre>
  223. <p>
  224. Then follow the installation instructions below.
  225. </p>
  226. <h3>Installing LuaJIT</h3>
  227. <p>
  228. Copy <tt>luajit.exe</tt> and <tt>lua51.dll</tt> (built in the <tt>src</tt>
  229. directory) to a newly created directory (any location is ok).
  230. Add <tt>lua</tt> and <tt>lua\jit</tt> directories below it and copy
  231. all Lua files from the <tt>src\jit</tt> directory of the distribution
  232. to the latter directory.
  233. </p>
  234. <p>
  235. There are no hardcoded
  236. absolute path names &mdash; all modules are loaded relative to the
  237. directory where <tt>luajit.exe</tt> is installed
  238. (see <tt>src/luaconf.h</tt>).
  239. </p>
  240. <p>
  241. The final directory layout should look like this:
  242. </p>
  243. <pre class="code">
  244. ├── luajit.exe
  245. ├── lua51.dll
  246. ├── <- put your own classic Lua/C API modules (*.dll) here
  247. └── lua
  248. ├── <- put your own Lua modules (*.lua) here
  249. └── jit
  250. ├── bc.lua
  251. └── (etc …)
  252. </pre>
  253. <h2 id="cross">Cross-compiling LuaJIT</h2>
  254. <p>
  255. First, let's clear up some terminology:
  256. </p>
  257. <ul>
  258. <li>Host: This is your development system, usually based on a x64 or x86 CPU.</li>
  259. <li>Target: This is the target system you want LuaJIT to run on, e.g. Android/ARM.</li>
  260. <li>Toolchain: This comprises a C compiler, linker, assembler and a matching C library.</li>
  261. <li>Host (or system) toolchain: This is the toolchain used to build native binaries for your host system.</li>
  262. <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>
  263. </ul>
  264. <p>
  265. The GNU Makefile-based build system allows cross-compiling on any host
  266. for any supported target:
  267. </p>
  268. <ul>
  269. <li>Yes, you need a toolchain for both your host <em>and</em> your target!</li>
  270. <li>Both host and target architectures must have the same pointer size.</li>
  271. <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>
  272. <li>On some distro versions, multilib conflicts with cross-compilers. The workaround is to install the x86 cross-compiler package <tt>gcc-i686-linux-gnu</tt> and use it to build the host part (<tt>HOST_CC=i686-linux-gnu-gcc</tt>).</li>
  273. <li>64 bit targets always require compilation on a 64 bit host.</li>
  274. </ul>
  275. <p>
  276. You need to specify <tt>TARGET_SYS</tt> whenever the host OS and the
  277. target OS differ, or you'll get assembler or linker errors:
  278. </p>
  279. <ul>
  280. <li>E.g. if you're compiling on a Windows or macOS host for embedded Linux or Android, you need to add <tt>TARGET_SYS=Linux</tt> to the examples below.</li>
  281. <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>
  282. <li>Don't forget to specify the same <tt>TARGET_SYS</tt> for the install step, too.</li>
  283. </ul>
  284. <p>
  285. Here are some examples where host and target have the same CPU:
  286. </p>
  287. <pre class="code">
  288. # Cross-compile to a 32 bit binary on a multilib x64 OS
  289. make CC="gcc -m32"
  290. # Cross-compile on Debian/Ubuntu for Windows (mingw32 package)
  291. make HOST_CC="gcc -m32" CROSS=i586-mingw32msvc- TARGET_SYS=Windows
  292. </pre>
  293. <p id="cross2">
  294. The <tt>CROSS</tt> prefix allows specifying a standard GNU cross-compile
  295. toolchain (Binutils, GCC and a matching libc). The prefix may vary
  296. depending on the <tt>--target</tt> the toolchain was built for (note the
  297. <tt>CROSS</tt> prefix has a trailing <tt>"-"</tt>). The examples below
  298. use the canonical toolchain triplets for Linux.
  299. </p>
  300. <p>
  301. Since there's often no easy way to detect CPU features at runtime, it's
  302. important to compile with the proper CPU or architecture settings:
  303. </o>
  304. <ul>
  305. <li>The best way to get consistent results is to specify the correct settings when building the toolchain yourself.</li>
  306. <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>
  307. <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>
  308. <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>
  309. </ul>
  310. <p>
  311. Here are some examples for targets with a different CPU than the host:
  312. </p>
  313. <pre class="code">
  314. # ARM soft-float
  315. make HOST_CC="gcc -m32" CROSS=arm-linux-gnueabi- \
  316. TARGET_CFLAGS="-mfloat-abi=soft"
  317. # ARM soft-float ABI with VFP (example for Cortex-A9)
  318. make HOST_CC="gcc -m32" CROSS=arm-linux-gnueabi- \
  319. TARGET_CFLAGS="-mcpu=cortex-a9 -mfloat-abi=softfp"
  320. # ARM hard-float ABI with VFP (armhf, most modern toolchains)
  321. make HOST_CC="gcc -m32" CROSS=arm-linux-gnueabihf-
  322. # ARM64
  323. make CROSS=aarch64-linux-gnu-
  324. # PPC
  325. make HOST_CC="gcc -m32" CROSS=powerpc-linux-gnu-
  326. # MIPS32 big-endian
  327. make HOST_CC="gcc -m32" CROSS=mips-linux-gnu-
  328. # MIPS32 little-endian
  329. make HOST_CC="gcc -m32" CROSS=mipsel-linux-gnu-
  330. # MIPS64 big-endian
  331. make CROSS=mips-linux- TARGET_CFLAGS="-mips64r2 -mabi=64"
  332. # MIPS64 little-endian
  333. make CROSS=mipsel-linux- TARGET_CFLAGS="-mips64r2 -mabi=64"
  334. </pre>
  335. <p>
  336. You can cross-compile for <b id="android">Android</b> using the <a href="https://developer.android.com/ndk/"><span class="ext">&raquo;</span>&nbsp;Android NDK</a>.
  337. Please adapt the environment variables to match the install locations and the
  338. desired target platform. E.g. Android&nbsp;4.1 corresponds to ABI level&nbsp;16.
  339. </p>
  340. <pre class="code">
  341. # Android/ARM64, aarch64, Android 5.0+ (L)
  342. NDKDIR=/opt/android/ndk
  343. NDKBIN=$NDKDIR/toolchains/llvm/prebuilt/linux-x86_64/bin
  344. NDKCROSS=$NDKBIN/aarch64-linux-android-
  345. NDKCC=$NDKBIN/aarch64-linux-android21-clang
  346. make CROSS=$NDKCROSS \
  347. STATIC_CC=$NDKCC DYNAMIC_CC="$NDKCC -fPIC" \
  348. TARGET_LD=$NDKCC TARGET_AR="$NDKBIN/llvm-ar rcus" \
  349. TARGET_STRIP=$NDKBIN/llvm-strip
  350. # Android/ARM, armeabi-v7a (ARMv7 VFP), Android 4.1+ (JB)
  351. NDKDIR=/opt/android/ndk
  352. NDKBIN=$NDKDIR/toolchains/llvm/prebuilt/linux-x86_64/bin
  353. NDKCROSS=$NDKBIN/arm-linux-androideabi-
  354. NDKCC=$NDKBIN/armv7a-linux-androideabi16-clang
  355. make HOST_CC="gcc -m32" CROSS=$NDKCROSS \
  356. STATIC_CC=$NDKCC DYNAMIC_CC="$NDKCC -fPIC" \
  357. TARGET_LD=$NDKCC TARGET_AR="$NDKBIN/llvm-ar rcus" \
  358. TARGET_STRIP=$NDKBIN/llvm-strip
  359. </pre>
  360. <p>
  361. You can cross-compile for <b id="ios">iOS 3.0+</b> (iPhone/iPad) using the <a href="https://developer.apple.com/ios/"><span class="ext">&raquo;</span>&nbsp;iOS SDK</a>:
  362. </p>
  363. <p style="font-size: 8pt;">
  364. Note: <b>the JIT compiler is disabled for iOS</b>, because regular iOS Apps
  365. are not allowed to generate code at runtime. You'll only get the performance
  366. of the LuaJIT interpreter on iOS. This is still faster than plain Lua, but
  367. much slower than the JIT compiler. Please complain to Apple, not me.
  368. Or use Android. :-p
  369. </p>
  370. <pre class="code">
  371. # iOS/ARM64
  372. ISDKP=$(xcrun --sdk iphoneos --show-sdk-path)
  373. ICC=$(xcrun --sdk iphoneos --find clang)
  374. ISDKF="-arch arm64 -isysroot $ISDKP"
  375. make DEFAULT_CC=clang CROSS="$(dirname $ICC)/" \
  376. TARGET_FLAGS="$ISDKF" TARGET_SYS=iOS
  377. </pre>
  378. <h3 id="consoles">Cross-compiling for consoles</h3>
  379. <p>
  380. Building LuaJIT for consoles requires both a supported host compiler
  381. (x86 or x64) and a cross-compiler from the official console SDK.
  382. </p>
  383. <p>
  384. Due to restrictions on consoles, the JIT compiler is disabled and only
  385. the fast interpreter is built. This is still faster than plain Lua,
  386. but much slower than the JIT compiler. The FFI is disabled, too, since
  387. it's not very useful in such an environment.
  388. </p>
  389. <p>
  390. The following commands build a static library <tt>libluajit.a</tt>,
  391. which can be linked against your game, just like the Lua library.
  392. </p>
  393. <p>
  394. To cross-compile for <b id="ps3">PS3</b> from a Linux host (requires
  395. 32&nbsp;bit GCC, i.e. multilib Linux/x64) or a Windows host (requires
  396. 32&nbsp;bit MinGW), run this command:
  397. </p>
  398. <pre class="code">
  399. make HOST_CC="gcc -m32" CROSS=ppu-lv2-
  400. </pre>
  401. <p>
  402. To cross-compile for the other consoles from a Windows host, open a
  403. "Native Tools Command Prompt for VS". You need to choose either the 32
  404. or the 64&nbsp;bit version of the host compiler to match the target.
  405. Then <tt>cd</tt> to the <tt>src</tt> directory below the source code
  406. and run the build command given in the table:
  407. </p>
  408. <table class="compat">
  409. <tr class="compathead">
  410. <td class="compatname">Console</td>
  411. <td class="compatbits">Bits</td>
  412. <td class="compatx">Build Command</td>
  413. </tr>
  414. <tr class="odd separate">
  415. <td class="compatname"><b id="ps4">PS4</b></td>
  416. <td class="compatbits">64</td>
  417. <td class="compatx"><tt>ps4build</tt></td>
  418. </tr>
  419. <tr class="even">
  420. <td class="compatname"><b id="ps5">PS5</b></td>
  421. <td class="compatbits">64</td>
  422. <td class="compatx"><tt>ps5build</tt></td>
  423. </tr>
  424. <tr class="odd">
  425. <td class="compatname"><b id="psvita">PS Vita</b></td>
  426. <td class="compatbits">32</td>
  427. <td class="compatx"><tt>psvitabuild</tt></td>
  428. </tr>
  429. <tr class="even">
  430. <td class="compatname"><b id="xbox360">Xbox 360</b></td>
  431. <td class="compatbits">32</td>
  432. <td class="compatx"><tt>xedkbuild</tt></td>
  433. </tr>
  434. <tr class="odd">
  435. <td class="compatname"><b id="xboxone">Xbox One</b></td>
  436. <td class="compatbits">64</td>
  437. <td class="compatx"><tt>xb1build</tt></td>
  438. </tr>
  439. <tr class="even">
  440. <td class="compatname"><b id="nx32">Nintendo Switch NX32</b></td>
  441. <td class="compatbits">32</td>
  442. <td class="compatx"><tt>nxbuild</tt></td>
  443. </tr>
  444. <tr class="odd">
  445. <td class="compatname"><b id="nx64">Nintendo Switch NX64</b></td>
  446. <td class="compatbits">64</td>
  447. <td class="compatx"><tt>nxbuild</tt></td>
  448. </tr>
  449. </table>
  450. <p>
  451. Please check out the comments in the corresponding <tt>*.bat</tt>
  452. file for more options.
  453. </p>
  454. <h2 id="embed">Embedding LuaJIT</h2>
  455. <p>
  456. LuaJIT is API-compatible with Lua 5.1. If you've already embedded Lua
  457. into your application, you probably don't need to do anything to switch
  458. to LuaJIT, except link with a different library:
  459. </p>
  460. <ul>
  461. <li>It's strongly suggested to build LuaJIT separately using the supplied
  462. build system. Please do <em>not</em> attempt to integrate the individual
  463. source files into your build tree. You'll most likely get the internal build
  464. dependencies wrong or mess up the compiler flags. Treat LuaJIT like any
  465. other external library and link your application with either the dynamic
  466. or static library, depending on your needs.</li>
  467. <li>If you want to load C modules compiled for plain Lua
  468. with <tt>require()</tt>, you need to make sure the public symbols
  469. (e.g. <tt>lua_pushnumber</tt>) are exported, too:
  470. <ul><li>On POSIX systems you can either link to the shared library
  471. or link the static library into your application. In the latter case
  472. you'll need to export all public symbols from your main executable
  473. (e.g. <tt>-Wl,-E</tt> on Linux) and add the external dependencies
  474. (e.g. <tt>-lm -ldl</tt> on Linux).</li>
  475. <li>Since Windows symbols are bound to a specific DLL name, you need to
  476. link to the <tt>lua51.dll</tt> created by the LuaJIT build (do not rename
  477. the DLL). You may link LuaJIT statically on Windows only if you don't
  478. intend to load Lua/C modules at runtime.
  479. </li></ul>
  480. </li>
  481. </ul>
  482. <p>Additional hints for initializing LuaJIT using the C API functions:</p>
  483. <ul>
  484. <li>Here's a
  485. <a href="http://lua-users.org/wiki/SimpleLuaApiExample"><span class="ext">&raquo;</span>&nbsp;simple example</a>
  486. for embedding Lua or LuaJIT into your application.</li>
  487. <li>Make sure you use <tt>luaL_newstate</tt>. Avoid using
  488. <tt>lua_newstate</tt>, since this uses the (slower) default memory
  489. allocator from your system (no support for this on 64&nbsp;bit architectures).</li>
  490. <li>Make sure you use <tt>luaL_openlibs</tt> and not the old Lua 5.0 style
  491. of calling <tt>luaopen_base</tt> etc. directly.</li>
  492. <li>To change or extend the list of standard libraries to load, copy
  493. <tt>src/lib_init.c</tt> to your project and modify it accordingly.
  494. Make sure the <tt>jit</tt> library is loaded, or the JIT compiler
  495. will not be activated.</li>
  496. <li>The <tt>bit.*</tt> module for bitwise operations
  497. is already built-in. There's no need to statically link
  498. <a href="https://bitop.luajit.org/"><span class="ext">&raquo;</span>&nbsp;Lua BitOp</a> to your application.</li>
  499. </ul>
  500. <h2 id="distro">Hints for Distribution Maintainers</h2>
  501. <p>
  502. The LuaJIT build system has extra provisions for the needs of most
  503. POSIX-based distributions. If you're a package maintainer for
  504. a distribution, <em>please</em> make use of these features and
  505. avoid patching, subverting, autotoolizing or messing up the build system
  506. in unspeakable ways.
  507. </p>
  508. <p>
  509. There should be absolutely no need to patch <tt>luaconf.h</tt> or any
  510. of the Makefiles. And please do not hand-pick files for your packages &mdash;
  511. simply use whatever <tt>make install</tt> creates. There's a reason
  512. for all the files <em>and</em> directories it creates.
  513. </p>
  514. <p>
  515. The build system uses GNU make and auto-detects most settings based on
  516. the host you're building it on. This should work fine for native builds,
  517. even when sandboxed. You may need to pass some of the following flags to
  518. <em>both</em> the <tt>make</tt> and the <tt>make install</tt> command lines
  519. for a regular distribution build:
  520. </p>
  521. <ul>
  522. <li><tt>PREFIX</tt> overrides the installation path and should usually
  523. be set to <tt>/usr</tt>. Setting this also changes the module paths and
  524. the paths needed to locate the shared library.</li>
  525. <li><tt>DESTDIR</tt> is an absolute path which allows you to install
  526. to a shadow tree instead of the root tree of the build system.</li>
  527. <li><tt>MULTILIB</tt> sets the architecture-specific library path component
  528. for multilib systems. The default is <tt>lib</tt>.</li>
  529. <li>Have a look at the top-level <tt>Makefile</tt> and <tt>src/Makefile</tt>
  530. for additional variables to tweak. The following variables <em>may</em> be
  531. overridden, but it's <em>not</em> recommended, except for special needs
  532. like cross-builds:
  533. <tt>BUILDMODE, CC, HOST_CC, STATIC_CC, DYNAMIC_CC, CFLAGS, HOST_CFLAGS,
  534. TARGET_CFLAGS, LDFLAGS, HOST_LDFLAGS, TARGET_LDFLAGS, TARGET_SHLDFLAGS,
  535. TARGET_FLAGS, LIBS, HOST_LIBS, TARGET_LIBS, CROSS, HOST_SYS, TARGET_SYS
  536. </tt></li>
  537. </ul>
  538. <p>
  539. The build system has a special target for an amalgamated build, i.e.
  540. <tt>make amalg</tt>. This compiles the LuaJIT core as one huge C file
  541. and allows GCC to generate faster and shorter code. Alas, this requires
  542. lots of memory during the build. This may be a problem for some users,
  543. that's why it's not enabled by default. But it shouldn't be a problem for
  544. most build farms. It's recommended that binary distributions use this
  545. target for their LuaJIT builds.
  546. </p>
  547. <p>
  548. The tl;dr version of the above:
  549. </p>
  550. <pre class="code">
  551. make amalg PREFIX=/usr && \
  552. make install PREFIX=/usr DESTDIR=/tmp/buildroot
  553. </pre>
  554. <p>
  555. Finally, if you encounter any difficulties, please
  556. <a href="contact.html">contact me</a> first, instead of releasing a broken
  557. package onto unsuspecting users. Because they'll usually gonna complain
  558. to me (the upstream) and not you (the package maintainer), anyway.
  559. </p>
  560. <br class="flush">
  561. </div>
  562. <div id="foot">
  563. <hr class="hide">
  564. Copyright &copy; 2005-2025
  565. <span class="noprint">
  566. &middot;
  567. <a href="contact.html">Contact</a>
  568. </span>
  569. </div>
  570. </body>
  571. </html>