raw

Architecture

Module Organization

The codebase is organized into self-contained modules in src/:

Core Libraries (Lua + C):

std/ - Standard library
- filesystem (std.fs)
- process (std.ps)
- UTF-8 (std.utf)
- text (std.txt)
- tables (std.tbl)
- conversions (std.conv)
- MIME types (std.mime)
- logging (std.logger)
term/ - Terminal I/O with Kitty keyboard & graphic protocols support, widgets, TSS (Terminal Style Sheets)
crypto/ - Cryptography via LITLS
lev/ - Async I/O runtime: epoll event loop, TCP/UDP sockets with TLS 1.3 via LITLS
mneme/ - Embedded key-value DB with FT and vector support
lem/ - LEM text editor
zlib/ - Deflate, zlib-wrapped, and gzip compression, CRC-32/Adler-32 checksums via miniz
evdev/ - Linux input devices (joysticks/gamepads): device identity, per-axis calibration, raw event stream

Pure Lua Libraries:

shell/ - The Lilush Shell implementation (see Shell Architecture below)
git/ - Pure-Lua git repository reader (git: objects, refs, index), packfile generation (git.pack), shell prompt status (git.prompt)
argparser/ - Argument parsing
markdown/ - Markdown parser and renderers (static, streaming, HTML)
redis/ - Async Redis protocol client (requires lev.run() context)
dns/ - DNS client library (caching, CNAME following, failover, UDP/TCP/DoT transports)
testimony/ - Minimal testing framework for Lilush
theme/ - Central TSS-based styling for shell, markdown, and agent
lilpack/ - LILPACK package system (MNEME-backed module loading)
http/ - HTTP client and server, SSE streaming, URL parsing, form-data encoding/parsing, read-only git smart-HTTP serving (http.git)

C-only Libraries:

cjson/ - Fast JSON encoding/decoding
wireguard/ - WireGuard client bindings
inotify/ - File system event monitoring
litls/ - Lilush TLS stack

Shell Architecture

Consult SHELL.md for the Lilush Shell (src/shell/) detailed overview. The shell has three built-in modes: shell (F1), lua REPL (F2), and wiki viewer (F3). The wiki mode opens self-describing MNEME databases for browsing, searching, and viewing content — see WIKIDB.md.

Binary Preloading System

Lilush embeds all modules in the binary:

Lua modules - Compiled to bytecode, embedded as C char arrays
C modules - Statically linked, registered via luaL_Reg
Preloading - Both registered in package.preload before Lua execution

The c_tmpl template generates:

mod_lua__t lua_preload[] - Array of Lua bytecode modules
luaL_Reg c_preload[] - Array of C module loaders
preload_modules(L) - Populates package.preload

Module Registration

Adding a new Lua module:

Create files in src/yourmodule/*.lua
Add module to buildgen/modinfo.lua luamods section
Add to whichever app configs need it (e.g. buildgen/apps/lilush.lua, buildgen/apps/lilu.lua) luamods array

Adding a new C module:

Create source in src/yourmodule/*.c with luaopen_* function
Create src/yourmodule/Makefile
Add to buildgen/modinfo.lua c_libs section
Add to whichever app configs need it (e.g. buildgen/apps/lilush.lua, buildgen/apps/lilu.lua) c_libs array

File Paths and Package Loading

Lilush uses the LILPACK system for package loading. On startup, lilpack.init() strips all default Lua searchers except the preload searcher, then installs two custom searchers:

LILPACK searcher - Loads modules from MNEME-backed .lilpack databases in ~/.local/share/lilush/packages/
Script-local searcher - Tries ./module.lua and ./module/init.lua relative to CWD

After initialization, package.path is set to an empty string. See LILPACK.md for the full package system specification.