LSL modules, libraries and packages
How load works, where modules are searched, which libraries are bundled with LSL 0.10.2 and
how to install per-user libraries from the LSL registry.
load syntax
load json # members as json.encode(...)
load tensor as t # alias: t.from_values(...)
load os, time # several modules (max 32) in one line
load time, os as a # shared alias: a.monotonic() and a.which(...)
from helpers load area # import a single symbol
from helpers load area as surface
- Each
.lslfile is a module; its public variables, functions and classes are available under the prefixname.. - With a shared alias, a member is looked up in the listed modules in order and the first module that exports it wins; if none does, the error points at the first module.
- Imports are static: everything is resolved at compile time and linked into the program.
No module loader runs at run time, so a compiled ELF contains all code it needs. Scripts run
with
lsl file.lslpick up changed libraries on the next run; standalone binaries must be recompiled. - Module symbols get a deterministic namespace prefix. Classes marked
ctype Privateare not reachable from outside; public classes can be constructed directly.
Note (0.10.2): from lux load l fails because the shipped lux module has no l
function (see stdlib-core.md). from MODULE load NAME works with your own
modules.
Search order
load foo.bar looks for foo/bar.lsl in this order:
- relative to the importing source file,
- compiler-internal modules,
- bundled/system stdlib
<prefix>/lib/lsl/stdlib/(/usr/lib/lsl/stdlibon LuxOS), - per-user libraries
~/.local/lib/lsl/stdlib/.
Bundled modules cannot be shadowed by a local or per-user file of the same name. Exception
(since 0.9.1): load ai uses a per-user aikit.lsl if it is newer than the bundled ai.
A missing library is error E3001 with the name and the exact import location (also for
imports inside another library); the message suggests checking the local file and
lsl search NAME / lsl install NAME. Nothing is downloaded automatically. A missing bundled
module means a damaged LSL installation. An existing but unreadable module is E3002.
Bundled libraries in 0.10.2
Listed by lsl list as bundled (descriptions from lsl about NAME):
| Module | Purpose |
|---|---|
ai |
OpenAI-compatible chat client with tools (function calling), live SSE streaming, structured errors and retries |
bigint |
arbitrary-precision signed integers (BigInt) |
config |
helpers for declarative configuration modules evaluated by lsl config |
configure |
generates the native configuration evaluator wrapper (internal, used by lsl-configure) |
cuda |
optional NVIDIA CUDA backend in a separate worker process |
env |
environment variables and .env files |
fd |
raw file-descriptor I/O for devices, sockets, ioctl/mmap, bounded procfs/sysfs reads |
http |
HTTP(S) client (dictionary results) |
httpserver |
bounded HTTP/1.1 server and static files (also behind lsl server) |
json |
JSON encoder/decoder (4 MiB input limit, strict errors) |
lconf |
strict dependency-manifest codec (config.lconf) for .lux package archives |
lux |
core module: name and small helpers |
luxos |
declarative system configuration engine for LuxOS |
math |
mathematics and statistics |
native |
restricted fork-isolated ABI for self-contained native kernels |
os |
run programs via direct execve with argv, PATH lookup; never a shell |
plugin |
process plugin ABI v1 (JSON on stdin/stdout) |
process |
structured process helpers (separate stdout/stderr, stdin, streaming) |
random |
Python-style pseudo-random numbers (MT19937 Random(seed), SystemRandom) |
requests |
Python-style HTTP client with Response objects |
sandbox |
capability-oriented process sandbox used by lsl sandbox |
system |
imperative LuxOS/Debian administration helpers (packages, services, users, files) |
tensor |
dense CPU tensors over FloatArray with optional CUDA dispatch |
time |
wall clock, monotonic timing, sleep, UTC formatting |
tui |
full-screen terminal toolkit (cbreak, alternate screen, key decoding) |
unixsock |
Unix-domain sockets with file-descriptor passing |
Optional registry packages (install with lsl install NAME) include display (X11 /
framebuffer / DRM output), gfx (2D raster graphics), ui (widgets), css (styles),
input (evdev keyboard/pointer), x11, term (raw terminal control), shell (explicit
/bin/sh -c runner), sqlite (SQLite through the sqlite3 CLI) and aikit (standalone
updatable AI library). Run lsl search for the current catalog.
API details: stdlib-core.md, stdlib-system.md, stdlib-network-ai.md, stdlib-graphics-io.md, stdlib-compute.md.
Installing libraries from the registry
lsl search # whole catalog
lsl search text # search names and descriptions (case-insensitive)
lsl install textkit # download, verify SHA-256, compile-check, install atomically
lsl install --config libs.conf # install names from an LF-separated file
lsl install --tui # interactive catalog
lsl update textkit # update one per-user library
lsl list # bundled and user libraries with paths (offline)
lsl check textkit # exit 0 if installed, 1 if missing, 2 invalid arguments (offline)
lsl origin textkit # verify recorded SHA-256 and print origin/source URL
lsl about textkit # short description (leading comment of the source)
- Registry:
https://lsl.lux-ai.cz/packages(catalog v1catalog.json);LSL_REGISTRYoverrides it for development. Metadata: name, version, description, license, size, source, SHA-256. Invalid names, duplicates, unsafe paths and control characters are rejected. - Install verifies the real source and its SHA-256 and checks that it compiles, without running it. Declared dependencies are verified and installed first; a cycle or bad hash stops the installation (already installed dependencies may stay).
lsl searchexit codes: 0 match, 1 no match or registry error, 2 invalid arguments. A network error is an error, not an empty catalog.- Downloads use the system
curl, verification the systemsha256sum; no shell install scripts are run.
TUI package manager (lsl install --tui)
Arrows, Home/End, PageUp/PageDown browse; / filters (Enter confirm, Esc cancel); Space or
Enter marks a library (marks survive filter changes); i offers to install the marked ones and
y confirms; q, Ctrl-C or Ctrl-D quit. A failed item does not undo earlier successful
installs (not a transaction). Requires an interactive terminal other than dumb.
Libraries and sudo
Per-user libraries live in ~/.local/lib/lsl/stdlib of the user who ran lsl install. With
sudo, HOME usually becomes /root, so sudo lsl list, sudo lsl check NAME or
sudo lsl program.lsl do not see the normal user's libraries, and sudo lsl install NAME
installs for root. Install and verify user libraries without sudo. Updating LSL itself does
not delete user libraries.
Project layout
A larger project usually keeps a main file and modules next to it:
myapp/
main.lsl # load helpers ; load util.text
helpers.lsl
util/text.lsl
.env # read by `load env` (keep secrets out of the source)
Run with lsl main.lsl or build with lsl compile main.lsl myapp.