Template
feat(ext): add extension discovery and loading
Extension discovery (plan todo 20): scans --ext-dir dirs, STUPIDTOOLS_EXT, the XDG user dir and a builtin-ext dir for *.lua modules, runs each in the sandboxed Lua runtime, and enumerates its registrations; the builtin C/C++ modules load first via st_ext_init_builtins. Fail-fast with an error naming file and line on any malformed/sandbox-violating module. The CLI gains a repeatable --ext-dir flag; with flag or env present main.c runs discovery and prints 'loaded extension: ...' lines from actual registrations (interim wiring until todo 23). Note: src/Makefile.am gained the ext + vendored Lua sources because the binary otherwise cannot link discovery -- required for the root-verifiable CLI acceptance.
This commit is contained in:
@@ -0,0 +1,45 @@
|
||||
# builtin-ext/ — builtin extension directory
|
||||
|
||||
The directory of extension modules that ship with stupidtools (plan
|
||||
todo 20). It is currently empty on purpose; it exists to lock the
|
||||
convention.
|
||||
|
||||
## What goes here
|
||||
|
||||
Lua extension modules (`*.lua`) that load by default on every run. A
|
||||
module registers checks and languages through the sandboxed runtime's
|
||||
`st` API:
|
||||
|
||||
```lua
|
||||
st.register_check("magic")
|
||||
st.register_language("fortran")
|
||||
```
|
||||
|
||||
Only regular files with a `.lua` suffix are loaded (dotfiles are
|
||||
skipped); anything else here — this README included — is ignored by
|
||||
discovery. Files load in bytewise-lexicographic order.
|
||||
|
||||
## How discovery finds this directory
|
||||
|
||||
`st_ext_discover()` (src/ext/discovery.c) scans this directory LAST in
|
||||
the search order:
|
||||
|
||||
1. each `--ext-dir` directory (repeatable flag),
|
||||
2. each `STUPIDTOOLS_EXT` entry (colon-separated environment list),
|
||||
3. the user directory: `$XDG_DATA_HOME/stupidtools/ext`, falling back
|
||||
to `$HOME/.local/share/stupidtools/ext`,
|
||||
4. this directory.
|
||||
|
||||
The location is the `STUPIDTOOLS_BUILTIN_EXT_DIR` macro — currently the
|
||||
literal `builtin-ext`, resolved relative to the working directory of
|
||||
the running binary (fine for the in-repo layout). When an installed
|
||||
layout arrives, the build will override it at compile time, e.g.
|
||||
`-DSTUPIDTOOLS_BUILTIN_EXT_DIR='"<prefix>/share/stupidtools/ext"'`, and
|
||||
ship modules here.
|
||||
|
||||
## Why it is empty today
|
||||
|
||||
The builtin C and C++ language modules are compiled C code
|
||||
(`src/ext/lang_c.c`, `src/ext/lang_cpp.c`), not Lua, so nothing needs
|
||||
to live here yet. The first shipped Lua module arrives with the example
|
||||
extension todo and could serve as a fixture for this location.
|
||||
Reference in New Issue
Block a user