README

Pascal bindings to Lua 5.4 C API (and LuaJIT)

Free Pascal units to build dynamic libraries (C modules) loadable from Lua 5.4 via require().

• lua54.pas — Lua 5.4 core API (lua.h)
• lauxlib54.pas — Auxiliary library (lauxlib.h)
• lualib54.pas — Standard libraries (lualib.h), optional, for embedding a Lua host in Pascal

LuaJIT (отдельный стек, C API 5.1 / LuaJIT): luajit51.pas, lauxlib51.pas, lualib51.pas, luajit_ext.pas; пакет Lazarus package/lualib_jit.lpk; пример example/run_luajit.lpr. Подробнее — docs/USAGE.md §10.

Compiler: Free Pascal (e.g. from fpcupdeluxe in C:\fpcupdeluxe).

Одни и те же единицы используются для двух сценариев: (1) вызов Lua из Pascal — программа-хост создаёт состояние, подключает библиотеки, выполняет скрипты; (2) вызов Pascal из Lua — ваш код в виде DLL загружается через require().

Подробная документация: docs/USAGE.md — как пользоваться библиотекой, писать свои модули, встраивать Lua в приложение, подключить пакет в Lazarus (package/lualib.lpk для Lua 5.4, package/lualib_jit.lpk для LuaJIT), решать типичные проблемы.

Requirements

• Free Pascal (FPC) 3.0+
• Lua 5.4: interpreter and lua54.dll (Windows) or liblua.so.5.4 (Unix).
  Your module DLL will link to this library; the Lua executable must use the same library.
  The OS loader looks for lua54.dll (name is set in lua54.pas as LUA54_LIB): first the directory of the process exe (e.g. lua.exe when running from Lua, or your exe when running a host), then system dirs and PATH. See docs/USAGE.md §1.1.
• LuaJIT (optional): libluajit-5.1.so.2 (Unix) or lua51.dll (Windows); see LUAJIT_LIB in luajit51.pas and docs/USAGE.md §10.

Directory layout

lualib/
  src/
    lua54.pas      ??? core API
    lauxlib54.pas  ??? auxiliary
    lualib54.pas   ??? standard libs (optional)
    luajit51.pas   ??? LuaJIT core (lua.h 5.1 / LuaJIT)
    lauxlib51.pas  ??? LuaJIT auxiliary
    lualib51.pas   ??? LuaJIT standard libs + jit/ffi
    luajit_ext.pas ??? luaJIT_setmode (luajit.h)
  example/
    mymodule.lpr         ??? ???????????? C-???????????? ?????? Lua (DLL)
    run_lua.lpr          ??? ???????????? ?????????? (???????????? ??????????????)
    run_luajit.lpr       ??? ???????????? ?????????? LuaJIT
    test_luajit.lua      ??? ???????????????? run_luajit
    callbacks.lpr        ??? ????????????????: ?????????? Lua ???? Pascal ?? ???????????????? ??????????????
    callbacks_demo.lua   ??? ???????? ?????? callbacks
    test_mymodule.lua    ??? ?????????? mymodule ???? Lua
  package/
    lualib.lpk       ??? ?????????? Lazarus (Lua 5.4)
    lualib_jit.lpk   ??? ?????????? Lazarus (LuaJIT)
  docs/
    USAGE.md       ??? ?????????????????????? ???? ??????????????????????????
  build.cmd        ??? ???????????? ?????????????? (Windows x86_64)
  build.sh              ??? ???????????? ?????????????? (Linux/Unix)
  build_run_luajit.sh   ??? ???????????? ?????????????? ?????????? LuaJIT (Linux/Unix)
  build.ps1        ??? ???????????? ?????????????? (PowerShell)
  README.md

Building the example module

From the project root:

build.cmd

Or with PowerShell:

.\build.ps1

Or manually (x86_64 Windows):

fpc -MObjFPC -Scghi -O2 -Twin64 -Px86_64 -Fu"src" -Fi"src" example\mymodule.lpr

For 32-bit Windows use -Ti386-win32 -Pi386 and ensure lua54.dll is 32-bit.

Linux: run ./build.sh (requires FPC and liblua.so.5.4). Output: example/mymodule.so. Use lua test_mymodule.lua from the example directory; the script supports both .dll (Windows) and .so (Linux).

Output (Windows): example\mymodule.dll.

Using the module from Lua 5.4

1. Put mymodule.dll in a directory listed in package.cpath (e.g. same folder as lua54.exe or .;./?.dll).
2. Ensure lua54.dll is in the same directory as the Lua executable or in PATH.
3. В Lua или запустите пример:

local m = require('mymodule')
print(m.hello())   -- Hello from Pascal!

Из каталога example (если mymodule.dll и lua54.dll там же или в PATH):

lua54 test_mymodule.lua

Creating your own module

1. Create a library project (not program):
   pascalCopy

   library myname;
   uses lua54, lauxlib54;

2. Implement one or more C-callable functions:
   pascalCopy

   function my_func(L: Plua_State): Integer; cdecl;
   begin
     lua_pushstring(L, 'result');
     Result := 1;   // number of return values
   end;

3. Export the opener. Lua looks for luaopen_<module> (dots in module name become _):
   pascalCopy

   function luaopen_myname(L: Plua_State): Integer; cdecl;
   const
     lib: array[0..1] of luaL_Reg = (
       (name: 'my_func'; func: @my_func),
       (name: nil; func: nil)
     );
   begin
     luaL_checkversion(L);
     lua_createtable(L, 0, 1);
     luaL_setfuncs(L, @lib[0], 0);
     Result := 1;
   end;
   
   exports
     luaopen_myname name 'luaopen_myname';

4. Build with -Fu pointing to the folder containing lua54.pas and lauxlib54.pas.

Using from Lazarus

Open package/lualib.lpk in Lazarus, then Compile and Use → Install. In your project: Project → Project Inspector → Add → New requirement → choose lualib. Then uses lua54, lauxlib54, lualib54; in code. When using Lazarus, no build scripts are needed — use Run/Build in the IDE. See docs/USAGE.md §8.

Embedding Lua in a Pascal program (host)

Use lua54, lauxlib54 and lualib54. Create state with luaL_newstate, then luaL_openlibs(L), then load/run scripts with luaL_loadfile/lua_pcall or luaL_loadstring/lua_pcall. See docs/USAGE.md §7 and example/run_lua.lpr.

Build the example host (from project root):

fpc -Fu"src" -Fi"src" example\run_lua.lpr

Run: run_lua (runs a built-in Lua snippet) or run_lua script.lua. Place lua54.dll next to the exe or in PATH.

Configuring the Lua library name

If your Lua 5.4 shared library has a different name, set the unit constant before use. In lua54.pas the default is:

• Windows: lua54.dll
• Unix: liblua.so.5.4

You can define a custom name at compile time, or copy lua54.pas and change LUA54_LIB in the const section.

License

Same as Lua: MIT. Pascal bindings and example are provided as-is.