Lua Extended Library

Lua Extended Library is a Lua 5.4 native extension written in Go (via cgo) that provides practical system and utility modules with an async event loop.

It is designed to let Lua code look synchronous while the underlying work (file I/O and other native tasks) runs asynchronously and resumes through a cooperative event loop.

Important

• This project is still under development and is considered unstable.
• It works on Windows, Linux, and macOS. For building on Windows, MSYS2 is required.

What this project provides

• Native Lua module compiled as a shared library (extdlib.so)
• Lua wrapper with friendly API (extdlib.lua)
• Async/event loop primitives to avoid callback-heavy code
• Utility modules for:
  • Filesystem
  • Path
  • String helpers
  • Regex
  • Crypto
  • Timer
  • OS/process helpers
  • HTTP (currently partial)

Requirements

The Makefile checks these binaries and packages:

• go
• gcc
• pkg-config
• lua5.4
• Lua 5.4 development package with pkg-config metadata (lua5.4.pc), usually from liblua5.4-dev

Also required:

• make

Quick install (Debian/Ubuntu)

sudo apt update
sudo apt install -y make golang gcc pkg-config lua5.4 liblua5.4-dev

Supported architectures

The Makefile auto-detects host architecture and maps it to Go arch:

• x86_64 -> amd64
• aarch64/arm64 -> arm64
• armv7l -> arm

Build

make build

This creates:

• dist/extdlib.so
• dist/extdlib.lua

Run tests

make test

Basic usage

Most async-style APIs return:

• (err, result) where err is nil on success

When using modules that depend on async bridge/event-loop behavior, call them inside eventloop.start(...) (or an async task).

Example: filesystem read

local lxlib = require("dist.extdlib")

lxlib.eventloop.start(function()
	local err, content = lxlib.fs.readFile("README.md")
	if err then
		print("read error:", err.message)
		return
	end
	print("bytes:", #content)
end)

Example: path + string helpers

local lxlib = require("dist.extdlib")

local p = lxlib.path.join("src", "utils", "file.lua")
print("path:", p)
print("base:", lxlib.path.basename(p))
print("upper:", lxlib.string.toUpper("hello"))

Example: timers in the event loop

local lxlib = require("dist.extdlib")

lxlib.eventloop.start(function()
	local id = lxlib.timer.setInterval(500, function()
		print("tick")
	end)

	lxlib.timer.setTimeout(2000, function()
		lxlib.timer.clearTimer(id)
		print("interval cleared")
	end)
end)

Example: simple HTTP route

local lxlib = require("dist.extdlib")

lxlib.http.handle("GET", "/health", function(req, res)
	res.status = 200
	res.body = "ok"
end)

lxlib.http.listen("8080")

Module status (high level)

• Implemented: FS, OS, Path, Timer, Crypto, String, Regex, Event Loop, Bridge
• Partial/in progress: HTTP
• Planned/not yet complete: JSON, Net/TCP

Project layout

• extdlib/ Go native bindings and Lua wrapper
• tests/ Lua tests

Notes

• Build output is consumed in tests via require("dist.extdlib").
• If pkg-config cannot find lua5.4, install the Lua 5.4 dev package for your distro.