Documentation
This commit is contained in:
parent
677f05d69c
commit
665616f1e3
20
Makefile
20
Makefile
|
@ -9,6 +9,7 @@ CD=cd
|
||||||
AWK=awk
|
AWK=awk
|
||||||
GREP=grep
|
GREP=grep
|
||||||
SORT=sort
|
SORT=sort
|
||||||
|
TEST=test
|
||||||
|
|
||||||
# Config
|
# Config
|
||||||
worker_chroot = $(smr_var)/kore_worker
|
worker_chroot = $(smr_var)/kore_worker
|
||||||
|
@ -104,13 +105,13 @@ install: $(app_root) $(kmgr_chroot) $(parent_chroot) $(initscript) $(config) smr
|
||||||
|
|
||||||
$(config) : conf/smr.conf
|
$(config) : conf/smr.conf
|
||||||
$(Q)$(MKDIR) $(conf_path)
|
$(Q)$(MKDIR) $(conf_path)
|
||||||
$(Q)$(COPY) $< $@
|
$(Q)$(TEST) ! -e $@ && $(COPY) $< $@
|
||||||
|
|
||||||
$(initscript) : packaging/systemd/smr.service
|
$(initscript) : packaging/systemd/smr.service
|
||||||
$(Q)$(COPY) $< $@
|
$(Q)$(COPY) $< $@
|
||||||
|
|
||||||
cloc: ## calculate source lines of code in smr
|
cloc: ## calculate source lines of code in smr
|
||||||
cloc --force-lang="html",etlua --force-lang="lua",luasrc assets Makefile
|
cloc --force-lang="html",etlua --force-lang="lua",lua src assets Makefile
|
||||||
|
|
||||||
$(app_root):
|
$(app_root):
|
||||||
$(Q)$(MKDIR) $(app_root)
|
$(Q)$(MKDIR) $(app_root)
|
||||||
|
@ -153,7 +154,7 @@ $(built_sql): $(app_root)/sql/%.sql : src/sql/%.sql
|
||||||
$(Q)$(ECHO) "[copy] $@"
|
$(Q)$(ECHO) "[copy] $@"
|
||||||
$(Q)$(COPY) $^ $@
|
$(Q)$(COPY) $^ $@
|
||||||
|
|
||||||
$(built_tests) : $(app_root)/spec/% : spec/% $(app_root)/spec
|
$(built_tests): $(app_root)/spec/% : spec/% $(app_root)/spec
|
||||||
$(Q)$(ECHO) "[copy] $@"
|
$(Q)$(ECHO) "[copy] $@"
|
||||||
$(Q)$(COPY) $< $@
|
$(Q)$(COPY) $< $@
|
||||||
|
|
||||||
|
@ -161,15 +162,22 @@ $(app_root)/spec: $(app_root)
|
||||||
$(Q)$(MKDIR) $@
|
$(Q)$(MKDIR) $@
|
||||||
$(Q)$(MKDIR) $@/parser_tests
|
$(Q)$(MKDIR) $@/parser_tests
|
||||||
|
|
||||||
smr.so : $(src_files) conf/build.conf $(asset_files)
|
smr.so: $(src_files) conf/build.conf $(asset_files)
|
||||||
$(Q)$(ECHO) "[build] $@"
|
$(Q)$(ECHO) "[build] $@"
|
||||||
$(Q)$(KODEV) build
|
$(Q)$(KODEV) build
|
||||||
|
|
||||||
test : $(built) ## run the unit tests
|
test: $(built) ## run the unit tests
|
||||||
$(Q)$(CD) $(app_root) && busted -v --no-keep-going --exclude-tags "slow,todo,working"
|
$(Q)$(CD) $(app_root) && busted -v --no-keep-going --exclude-tags "slow,todo,working"
|
||||||
|
|
||||||
cov : $(built) ## code coverage (based on unit tests)
|
cov: $(built) ## code coverage (based on unit tests)
|
||||||
$(Q)$(RM) $(kore_chroot)/luacov.stats.out
|
$(Q)$(RM) $(kore_chroot)/luacov.stats.out
|
||||||
$(Q)$(CD) $(kore_chroot) && busted -v -c --no-keep-going --exclude-tags slow
|
$(Q)$(CD) $(kore_chroot) && busted -v -c --no-keep-going --exclude-tags slow
|
||||||
$(Q)$(CD) $(kore_chroot) && luacov endpoints/
|
$(Q)$(CD) $(kore_chroot) && luacov endpoints/
|
||||||
$(Q)$(ECHO) "open kore_chroot/luacov.report.out to view coverage results."
|
$(Q)$(ECHO) "open kore_chroot/luacov.report.out to view coverage results."
|
||||||
|
|
||||||
|
doc:
|
||||||
|
rm -rf .trblcache
|
||||||
|
~/Programs/trbldoc/trbldoc.sh src
|
||||||
|
cd .trblcache/built && python3 -m http.server
|
||||||
|
|
||||||
|
.PHONY: doc
|
||||||
|
|
|
@ -6,3 +6,4 @@ All other values are considered truethy.
|
||||||
In addition, tables may have a metatable that has a `__toboolean` function
|
In addition, tables may have a metatable that has a `__toboolean` function
|
||||||
to implement their own truethyness or falseyness. `false` should be used in
|
to implement their own truethyness or falseyness. `false` should be used in
|
||||||
places where a boolean is expected, and `nil` should be used otherwise.
|
places where a boolean is expected, and `nil` should be used otherwise.
|
||||||
|
|
||||||
|
|
|
@ -12,3 +12,9 @@ create_user(details :: table) :: boolean
|
||||||
```
|
```
|
||||||
Called when a user creates a user account on the site.
|
Called when a user creates a user account on the site.
|
||||||
|
|
||||||
|
```
|
||||||
|
authenticate(data :: table) :: number | nil, string
|
||||||
|
```
|
||||||
|
Called when a user attempts to log in. Return a number, userid if the login is successful, or nil and an error message if the login is not successful. By default, smr puts "user" and "passfile" fields into the data table.
|
||||||
|
|
||||||
|
|
||||||
|
|
|
@ -1,6 +1,12 @@
|
||||||
--[[ md
|
--[[ md
|
||||||
@name lua/addon
|
@name lua/addon
|
||||||
|
|
||||||
|
## Addon
|
||||||
|
|
||||||
|
Addons allow you to modify the behavior of smr without modifying the smr
|
||||||
|
source code. This is intended to make updates easier, and to modularize parts
|
||||||
|
of smr that are not minimally required.
|
||||||
|
|
||||||
Addon loader - Addons are either:
|
Addon loader - Addons are either:
|
||||||
* A folder with at least two files:
|
* A folder with at least two files:
|
||||||
- meta.lua - contains addon information
|
- meta.lua - contains addon information
|
||||||
|
@ -9,8 +15,10 @@ Addon loader - Addons are either:
|
||||||
* A sqlite3 database with a table "files" that has at least the columns
|
* A sqlite3 database with a table "files" that has at least the columns
|
||||||
* name :: TEXT - The filename
|
* name :: TEXT - The filename
|
||||||
* data :: BINARY - The file data
|
* data :: BINARY - The file data
|
||||||
And there are at least 2 rows with filenames `meta.lua` and `init.lua`
|
|
||||||
as described above. Addons should be placed in $SMR_ADDONS, defined in config.lua
|
And there are at least 2 rows with filenames `meta.lua` and `init.lua`
|
||||||
|
as described above. Addons should be placed in {{config/addons_folder},
|
||||||
|
defined in `config.lua`
|
||||||
|
|
||||||
The `meta.lua` file is run at worker init time (i.e. it will be run once for
|
The `meta.lua` file is run at worker init time (i.e. it will be run once for
|
||||||
each worker), and should return a table with at least the following information
|
each worker), and should return a table with at least the following information
|
||||||
|
|
|
@ -1,13 +1,47 @@
|
||||||
--[[
|
--[[ md
|
||||||
|
@name lua/hooks
|
||||||
|
|
||||||
Global functions that smr exposes that can be detoured by addons
|
Global functions that smr exposes that can be detoured by addons
|
||||||
|
|
||||||
|
]]
|
||||||
|
|
||||||
|
--[[ md
|
||||||
|
@name doc/detouring
|
||||||
|
|
||||||
|
# Detouring
|
||||||
|
|
||||||
|
In Lua, functions are given a name, but more generally, they values on a table
|
||||||
|
, perhaps the global table `_G`, and their names are the keys on the table.
|
||||||
|
When you want to modify a function that exists either in smr or in other addons
|
||||||
|
you can **detour** the function by saving a reference to the original function,
|
||||||
|
and then creating a new function that calls the original, maybe after doing
|
||||||
|
other work, or modifying the arguments. For example:
|
||||||
|
|
||||||
|
local pages = require("pages")
|
||||||
|
|
||||||
|
-- Get notified when the index page is rendered to the user
|
||||||
|
local oldindex = pages.index
|
||||||
|
function pages.index(...)
|
||||||
|
print("Index page is getting rendered!")
|
||||||
|
oldindex(...)
|
||||||
|
end
|
||||||
]]
|
]]
|
||||||
|
|
||||||
local api = {}
|
local api = {}
|
||||||
|
|
||||||
-- Called before any request processing. Returning true "traps" the request, and
|
--[[ md
|
||||||
-- does not continue calling smr logic. Well-behaved addons should check for
|
@name lua/hooks
|
||||||
-- "true" from the detoured function, and return true immediately if the check
|
|
||||||
-- succeeds.
|
## pre_request
|
||||||
|
|
||||||
|
Called before any request processing. Returning true "traps" the request, and
|
||||||
|
does not continue calling smr logic. Well-behaved addons should check for
|
||||||
|
"true" from the detoured function, and return true immediately if the check
|
||||||
|
succeeds.
|
||||||
|
|
||||||
|
@param req {{http_request}} - The request about to be processed
|
||||||
|
@returns boolean - If true, further processing is not done on this request.
|
||||||
|
]]
|
||||||
api.pre_request = function(req) end
|
api.pre_request = function(req) end
|
||||||
|
|
||||||
-- Called after smr request processing. Returning true "traps" the request.
|
-- Called after smr request processing. Returning true "traps" the request.
|
||||||
|
|
|
@ -4,6 +4,36 @@ It registers a bunch of global functions that get called from kore when users
|
||||||
visit particular pages. See src/smr.c for the names of the public functions.
|
visit particular pages. See src/smr.c for the names of the public functions.
|
||||||
See conf/smr.conf for the data that can be access in each function
|
See conf/smr.conf for the data that can be access in each function
|
||||||
]]
|
]]
|
||||||
|
|
||||||
|
--[[ md
|
||||||
|
@name lua
|
||||||
|
|
||||||
|
# Lua namespace
|
||||||
|
|
||||||
|
By default, smr will run init.lua defined by smr, and then addons in order,
|
||||||
|
see {{lua/addon}} for information on how smr loads addons. You can use any
|
||||||
|
of the modules that ship with smr by including them, and then calling the
|
||||||
|
functions defined in that module.
|
||||||
|
|
||||||
|
For example, the module {{lua/db}} holdes a reference to the sqlite3 database
|
||||||
|
that smr uses for data storage. If you addon needs to set up a table and
|
||||||
|
prepare sql statements for an api endpoint, you might set it up like this:
|
||||||
|
|
||||||
|
local db = require("db")
|
||||||
|
|
||||||
|
local oldconfigure = configure -- Hold a refrence to configure()
|
||||||
|
function configure(...) -- Detour the configure function
|
||||||
|
db.sqlassert(db.conn:exec([=[
|
||||||
|
CREATE TABLE IF NOT EXISTS foo (
|
||||||
|
id INTEGER AUTOINCREMENT PRIMARY KEY
|
||||||
|
value TEXT
|
||||||
|
);
|
||||||
|
]=]))
|
||||||
|
oldconfigure(...)
|
||||||
|
end
|
||||||
|
|
||||||
|
Be sure to always {{doc/appendix/detourin}}
|
||||||
|
]]
|
||||||
print("Really fast print from init.lua")
|
print("Really fast print from init.lua")
|
||||||
|
|
||||||
--Luarocks libraries
|
--Luarocks libraries
|
||||||
|
|
Loading…
Reference in New Issue