diff options
Diffstat (limited to 'modules/lua/docs')
| -rw-r--r-- | modules/lua/docs/README | 12 | ||||
| -rw-r--r-- | modules/lua/docs/basic-configuration.txt | 141 | ||||
| -rw-r--r-- | modules/lua/docs/building-from-subversion.txt | 72 | ||||
| -rw-r--r-- | modules/lua/docs/running-developer-tests.txt | 16 | ||||
| -rw-r--r-- | modules/lua/docs/writing-handlers.txt | 49 |
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") |