summaryrefslogtreecommitdiffstats
path: root/modules/lua/docs
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--modules/lua/docs/README12
-rw-r--r--modules/lua/docs/basic-configuration.txt141
-rw-r--r--modules/lua/docs/building-from-subversion.txt72
-rw-r--r--modules/lua/docs/running-developer-tests.txt16
-rw-r--r--modules/lua/docs/writing-handlers.txt49
5 files changed, 290 insertions, 0 deletions
diff --git a/modules/lua/docs/README b/modules/lua/docs/README
new file mode 100644
index 0000000..632945a
--- /dev/null
+++ b/modules/lua/docs/README
@@ -0,0 +1,12 @@
+Index of documents:
+ building-from-subversion.txt
+ Basic build instructions
+
+ basic-configuration.txt
+ Getting mod_wombat up and running
+
+ running-developer-tests.txt
+ How to set up and run the developer and regression tests
+
+ writing-handlers.txt
+ basics on writing handlers in mod_wombat \ No newline at end of file
diff --git a/modules/lua/docs/basic-configuration.txt b/modules/lua/docs/basic-configuration.txt
new file mode 100644
index 0000000..b837698
--- /dev/null
+++ b/modules/lua/docs/basic-configuration.txt
@@ -0,0 +1,141 @@
+See sample_httpd.conf for examples
+
+The basic module loading directive is
+ LoadModule lua_module modules/mod_lua.so
+
+The handler name is "lua-script" so you can use the normal
+AddHandler directive, such as "AddHandler lua-script .lua" to
+set anything ending in .lua to use mod_lua to evaluate
+
+mod_lua exports several additional directives:
+
+ LuaRoot /path/to/a/directory
+ Specify the base path which will be used to evaluate all
+ relative paths within mod_lua. If not specified they
+ will be resolved relative to the current working directory,
+ which may not always work well for a server.
+
+ LuaScope once|request|conn|server [max|min max]
+ Specify the lifecycle scope of the Lua interpreter which will
+ be used by handlers in this "Directory." The default is "once"
+
+ once: use the interpreter once and throw it away.
+
+ request: use the interpreter to handle anything based on
+ the same file within this request, which is also
+ request scoped.
+
+ conn: Same as request but attached to the connection_rec
+
+ server: This one is different than others because the
+ server scope is quite long lived, and multiple threads
+ will have the same server_rec. To accommodate this
+ server scoped interpreter are stored in an apr
+ resource list. The min and max arguments are intended
+ to specify the pool size, but are unused at this time.
+
+ LuaMapHandler uri-pattern /path/to/lua/script.lua [function-name]
+ This directive matches a uri pattern to invoke a specific
+ handler function in a specific file. It uses PCRE regular
+ expressions to match the uri, and supports interpolating
+ match groups into both the file path and the function name
+ be careful writing your regular expressions to avoid security
+ issues.
+
+ Examples:
+ LuaMapHandler /(\w+)/(/w+) /scripts/$1.lua handle_$2
+ This would match uri's such as /photos/show?id=9
+ to the file /scripts/photos.lua and invoke the
+ handler function handle_show on the lua vm after
+ loading that file.
+
+ LuaMapHandler /bingo /scripts/wombat.lua
+ This would invoke the "handle" function, which
+ is the default if no specific function name is
+ provided.
+
+ LuaPackagePath /path/to/include/?.lua
+ Add a path to lua's module search path. Follows the same
+ conventions as lua. This just munges the package.path in the
+ lua vms.
+
+ Examples:
+ LuaPackagePath /scripts/lib/?.lua
+ LuaPackagePath /scripts/lib/?/init.lua
+
+ LuaPackageCPath /path/to/include/?.soa
+ Add a path to lua's shared library search path. Follows the same
+ conventions as lua. This just munges the package.cpath in the
+ lua vms.
+
+ Examples:
+ LuaPackagePath /scripts/lib/?.so
+
+ LuaCodeCache stat|forever|never
+ Specify the behavior of the in-memory code cache. The default
+ is stat, which stats the top level script (not any included
+ ones) each time that file is needed, and reloads it if the
+ modified time indicates it is newer than the one it has
+ already loaded. The other values cause it to keep the file
+ cached forever (don't stat and replace) or to never cache the
+ file.
+
+ In general stat or forever is good production and stat or never
+ for development.
+
+ Examples:
+ LuaCodeCache stat
+ LuaCodeCache forever
+ LuaCodeCache never
+
+ LuaHookTranslateName /path/to/lua/script.lua hook_function_name
+ Add a hook (at APR_HOOK_MIDDLE) to the translate name phase of
+ request processing. The hook function receives a single
+ argument, the request_rec, and should return a status code,
+ which is either an HTTP error code, or the constants defined
+ in the apache2 module: apache2.OK, apache2.DECLINED, or
+ apache2.DONE.
+
+ For those new to hooks, basically each hook will be invoked
+ until one of them returns apache2.OK. If your hook doesn't
+ want to do the translation it should just return
+ apache2.DECLINED. If the request should stop processing, then
+ return apache2.DONE.
+
+ Example:
+ LuaHookTranslateName /scripts/conf/hooks.lua silly_mapper
+
+ -- /scripts/conf/hooks.lua --
+ function silly_mapper(r)
+ if r.uri == "/" then
+ r.file = "/var/www/home.lua"
+ return apache2.OK
+ else
+ return apache2.DECLINED
+ end
+ end
+
+ LuaHookFixups /path/to/lua/script.lua hook_function_name
+ Just like LuaHookTranslateName, but executed at the fixups phase
+
+ LuaHookMapToStorage /path/to/lua/script.lua hook_function_name
+ ...
+
+ LuaHookCheckUserID /path/to/lua/script.lua hook_function_name
+ ...
+
+ LuaHookTypeChecker /path/to/lua/script.lua hook_function_name
+ ...
+
+ LuaHookAuthChecker /path/to/lua/script.lua hook_function_name
+ ...
+
+ LuaHookAccessChecker /path/to/lua/script.lua hook_function_name
+ ...
+
+ LuaHookAuthChecker /path/to/lua/script.lua hook_function_name
+ ...
+
+ LuaHookInsertFilter /path/to/lua/script.lua hook_function_name
+ Not Yet Implemented
+
diff --git a/modules/lua/docs/building-from-subversion.txt b/modules/lua/docs/building-from-subversion.txt
new file mode 100644
index 0000000..98da7bf
--- /dev/null
+++ b/modules/lua/docs/building-from-subversion.txt
@@ -0,0 +1,72 @@
+Install Lua 5.1
+ http://www.lua.org/download.html
+
+ Lua does not use autoconf for compiling. This means that you do not use
+ ./configure. It has good build instructions, though, so hopefully things
+ will go smoothly.
+
+ I like to change the directory Lua installs to. In order to do this you
+ need to set LUA_TOP in the configuration makefile for Lua. For these
+ instructions I have set LUA_TOP to /Users/brianm/.opt/lua-5.1.2 -- you
+ will see this directory referred to later.
+
+
+Install Apache HTTPD 2.2
+ http://httpd.apache.org/download.cgi
+
+ You can build apache pretty much any way you like, as long as you enable
+ dynamic module loading (--enable-so) so that mod_wombat can be loaded.
+
+ You may user (and I encourage you to!) the threaded MPMs -- mod_wombat
+ plays nicely with them.
+
+ I build it with these flags:
+
+ ./configure --prefix=/Users/brianm/.opt/httpd-2.2.4-worker-wombat \
+ --with-mpm=worker \
+ --enable-so
+
+
+Install libapreq2
+ http://httpd.apache.org/apreq/download.cgi
+ The download link is in the page body, NOT under the "Download!" link
+ in the left hand column.
+
+ Right now, mod_wombat requires libapreq2 for parsing entity bodies. This
+ dependency will probably be made optional in the near future, but for now
+ you need it.
+
+ I build it with these flags:
+
+ ./configure --prefix=/Users/brianm/.opt/libapreq2-2.0.8 \
+ --with-apache2-apxs=/Users/brianm/.opt/httpd-2.2.4-worker-wombat/bin/apxs
+
+
+Install mod_wombat from subversion
+ http://svn.apache.org/repos/asf/httpd/mod_wombat/trunk
+
+ The first step, when building from subversion, is to bootstrap autoconf.
+ To do this run the bootstrap script:
+
+ ./bootstrap
+
+ The bootstrap script may report an error that it cannot find
+ libtoolize or glibtoolize. That is fine as long as it
+ doesn't report that it cannot find both of them. The script
+ just sets up the autoconf magic.
+
+ After that, it is a normal configure and build:
+
+ ./configure --with-lua=/Users/brianm/.opt/lua-5.1.2/ \
+ --with-apxs=/Users/brianm/.opt/httpd-2.2.4-worker-wombat/bin/apxs \
+ --with-apreq2=/Users/brianm/.opt/libapreq2-2.0.8/
+
+ If compiling (make) reports an error that it cannot find the
+ libapreq2 header file, please tell me ( brianm@apache.org )
+ as this occurs under some configurations but we haven't
+ hammered down the weird things libapreq2 does with its
+ install. If you build libapreq2 with a --prefix configuration
+ option, it always seems to work.
+
+
+That is it. To configure mod_wombat, look at the basic-configuration.txt document. \ No newline at end of file
diff --git a/modules/lua/docs/running-developer-tests.txt b/modules/lua/docs/running-developer-tests.txt
new file mode 100644
index 0000000..59eb990
--- /dev/null
+++ b/modules/lua/docs/running-developer-tests.txt
@@ -0,0 +1,16 @@
+-*- mode:org -*-
+* Building mod_lua
+ The first step is to build mod_lua per the instructions in
+ building-from-subversion.txt.
+
+* Build and install LuaSocket
+ http://www.cs.princeton.edu/~diego/professional/luasocket/
+ FreeBSD: /usr/ports/net/luasocket
+
+* Running Tests
+ 1. Replace apache's httpd.conf with test/test_httpd.conf
+ 2. Customize the new httpd.conf to match your directories
+ 3. Finally, to run the tests, start apache and run:
+ $ cd test
+ $ lua ./test.lua
+ FreeBSD: lua-5.1 ./test.lua
diff --git a/modules/lua/docs/writing-handlers.txt b/modules/lua/docs/writing-handlers.txt
new file mode 100644
index 0000000..2f18c41
--- /dev/null
+++ b/modules/lua/docs/writing-handlers.txt
@@ -0,0 +1,49 @@
+mod_lua always looks to invoke a function for the handler, rather than
+just evaluating a script body CGI style. A handler function looks
+something like this:
+
+ -- example.lua --
+ require "string"
+
+ function handle_something(r)
+ r.content_type = "text/plain"
+ r:puts("Hello Lua World!\n")
+
+ if r.method == 'GET' then
+ for k, v in pairs( r:parseargs() ) do
+ r:puts( string.format("%s: %s", k, v) )
+ end
+ elseif r.method == 'POST' then
+ for k, v in pairs( r:parsebody() ) do
+ r:puts( string.format("%s: %s", k, v) )
+ end
+ else
+ r:puts("unknown HTTP method " .. r.method)
+ end
+ end
+
+This handler function just prints out the uri or form encoded
+arguments to a plaintext page.
+
+This means (and in fact encourages) that you can have multiple
+handlers (or hooks, or filters) in the same script.
+
+Data Structures:
+ request_rec:
+ the request_rec is mapped in as a userdata. It has a metatable
+ which lets you do useful things with it. For the most part it
+ has the same fields as the request_rec struct (see httpd.h
+ until we get better docs here) many of which are writeable as
+ well as readable, and has (at least) the following methods:
+
+ r:puts("hello", " world", "!") -- print to response body
+
+ -- logging functions
+ r:debug("This is a debug log message")
+ r:info("This is an info log message")
+ r:notice("This is an notice log message")
+ r:warn("This is an warn log message")
+ r:err("This is an err log message")
+ r:alert("This is an alert log message")
+ r:crit("This is an crit log message")
+ r:emerg("This is an emerg log message")