Lilush documentation reference

Overview

Lilush is a statically compiled LuaJIT interpreter for Linux that bundles a curated collection of Lua modules and C libraries. It has two builds:

1. lilu - A batteries-included LuaJIT runtime with networking, crypto, terminal I/O, and system utilities

2. lilush - A feature-rich Linux shell Lilush Shell, built on top of lilu

Lilush is by design Linux only and not portable.

Documentation index

• ARCHITECTURE: Detailed architecture overview

• CONVENTIONS: Coding and naming conventions used in the project

• DEVELOPMENT: Building & testing instructions; build system architecture

• LEV: LEV async I/O runtime (event loop, UDP/TCP sockets, timers, combinators)

• LITLS: Lilush TLS stack (crypto primitives, X.509, TLS 1.3 protocol, Lua API)

• DNS: DNS client API, record types, cache, transports

• GFX: Terminal graphics (Kitty protocol), pixel canvas, sprites, pixel fonts, on-screen display, frame loop

• SOUND: Audio module (raw ALSA PCM playback, float32 sample buffers, in-process mixer, WAV loader, synth)

• SPEECH: English text-to-speech (Klatt-style formant synthesizer, voice presets/knobs, deterministic)

• MNEME: MNEME embedded key-value database

• WIKIDB: Wiki-DB convention for self-describing MNEME wiki databases

• LILPACK: LILPACK package system (convention, packer, management, shell integration)

• COMPLETION: Completion engine (provider/source/renderer interfaces, input integration)

• LEM: LEM text editor (modal editing, piece table, syntax highlighting, buffers, commands)

• SHELL: Lilush Shell (startup, config, modes, prompt, builtins, key bindings)

• LSH: LSH script format (syntax, arguments, builtins, differences from bash)

• TSS: TSS (Terminal Style Sheets) semantics, properties, cascading, and API contract

• THEMES: Theme system, live reloading, creating custom themes

• REDIS: Redis client API and connection config contract

• CREDITS: Credits, acknowledgements, licensing info

Entry Points

The lilush binary has multiple entry modes:

1. Interactive shell: lilush (no args)

2. Script execution: lilush /path/to/script.lua [args]

   • Example: lilush myscript.lua arg1 arg2

3. Lua code execution: lilush -e '<lua-code>'

   • Executes Lua code directly (like python -e or ruby -e)

   • Example: lilush -e "print('Hello from Lua')"

   • Example: lilush -e "local std = require('std'); print(std.fs.cwd())"

4. Shell command mode: lilush -c <shell-commands>

   • Executes lilush shell commands (mimics bash -c behavior)

   • Example: lilush -c "echo hello"

   • Note: This runs shell commands, NOT Lua code. Use -e for Lua code.

5. Built-in mode: Symlinked as builtin name executes that builtin

6. Version: lilush -v

See buildgen/entrypoints/lilush/main.c for implementation.

The minimal build, lilu has only (2), (3) and (6) entry modes from the above.

Common Gotchas

1. LuaJIT is not Lua 5.3+ - Uses Lua 5.1 + some 5.2 compat.

2. Static linking - All dependencies must be statically linkable. Dynamic loading (require with .so) won't work in final binary.

3. FFI disabled - LuaJIT FFI is disabled (-DLUAJIT_DISABLE_FFI) for size/security. Use C modules instead.

4. Built with musl libc, not glibc.