# HG changeset patch # User jbe # Date 1426959644 -3600 # Node ID b5d0c0ab3ce2e23cd5dc3128c658bd50b37db547 # Parent 2ddbb44680f72d9200fa7b5cc961c630969ca0ea Updated documentation; Switched version string to "2.0.0" diff -r 2ddbb44680f7 -r b5d0c0ab3ce2 Makefile --- a/Makefile Sat Mar 21 17:24:27 2015 +0100 +++ b/Makefile Sat Mar 21 18:40:44 2015 +0100 @@ -9,7 +9,7 @@ documentation:: rm -f doc/autodoc.tmp - $(LUA_BIN) framework/bin/autodoc.lua framework/cgi-bin/ framework/env/ libraries/ > doc/autodoc.tmp + $(LUA_BIN) framework/bin/autodoc.lua framework/env/ libraries/ > doc/autodoc.tmp cat doc/autodoc-header.htmlpart doc/autodoc.tmp doc/autodoc-footer.htmlpart > doc/autodoc.html rm -f doc/autodoc.tmp diff -r 2ddbb44680f7 -r b5d0c0ab3ce2 doc/apache.sample.conf --- a/doc/apache.sample.conf Sat Mar 21 17:24:27 2015 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,29 +0,0 @@ -# Apache modules cgi_module, env, rewrite and alias must be loaded before -# Take a look in your main apache configuration! - -RewriteEngine on -# do not rewrite static URLs -RewriteRule ^/webmcp-demo/static/(.*)$ /webmcp-demo/static/$1 -# dynamic URLs -RewriteRule ^/webmcp-demo/([^\?]*)(\?(.*))?$ /webmcp-demo/webmcp-wrapper.lua?_webmcp_path=$1&$3 - -# Directly serve static files -Alias /webmcp-demo/static /__INSERT_LOCAL_FILE_PATH_TO_DEMO_APPLICATION_HERE__/static - -# Connect extarnal path to the webmcp cgi interface -ScriptAlias /webmcp-demo/ /__INSERT_LOCAL_FILE_PATH_TO_WEBMCP_FRAMEWORK_HERE__/cgi-bin/ - -# Allow CGI execution for the webmcp CGI interface - - AllowOverride None - Options ExecCGI -MultiViews +SymLinksIfOwnerMatch - Order allow,deny - Allow from all - - -# Configure environment for demo application - - SetEnv WEBMCP_APP_BASEPATH '/__INSERT_LOCAL_FILE_PATH_TO_DEMO_APPLICATION_HERE__' - SetEnv WEBMCP_CONFIG_NAME 'demo' - - diff -r 2ddbb44680f7 -r b5d0c0ab3ce2 doc/autodoc-footer.htmlpart --- a/doc/autodoc-footer.htmlpart Sat Mar 21 17:24:27 2015 +0100 +++ b/doc/autodoc-footer.htmlpart Sat Mar 21 18:40:44 2015 +0100 @@ -1,7 +1,7 @@

diff -r 2ddbb44680f7 -r b5d0c0ab3ce2 doc/autodoc-header.htmlpart --- a/doc/autodoc-header.htmlpart Sat Mar 21 17:24:27 2015 +0100 +++ b/doc/autodoc-header.htmlpart Sat Mar 21 18:40:44 2015 +0100 @@ -55,20 +55,63 @@ color: #505050; } - WebMCP 1.2.6 Documentation + WebMCP 2.0.0 Documentation -

WebMCP 1.2.6 Documentation

WebMCP 2.0.0 Documentation

- WebMCP is a completely new web development framework, and has not been extensively tested yet. The API might change at any time, but in future releases there will be a list of all changes, which break downward compatibility. + WebMCP is a web development framework based on the Lua programming language (read more about Lua here).

Requirements

- WebMCP has been developed on Linux and FreeBSD. Using it with Mac OS X is completely untested; Microsoft Windows is not supported. Beside the operating system, the only mandatory dependencies for WebMCP are the programming language Lua version 5.1, PostgreSQL version 8.2 or higher, a C compiler, and a Webserver like Lighttpd or Apache. + WebMCP has been developed on Linux and FreeBSD. Using it with Mac OS X is untested as of yet; Microsoft Windows is not supported. Beside the operating system, the only mandatory dependencies for WebMCP are the programming language Lua version 5.3, the Moonbridge Network Server for Lua Applications version 0.4.0 or higher, PostgreSQL version 8.2 or higher, and a C compiler.

Installation

- After downloading the tar.gz package, unpack it, enter the unpacked directory and type make. If you use Mac OS X or if you experience problems during compilation, you need to edit the Makefile.options file prior to compilation. The framework itself will be available in the framework/ directory, while a demo application is available in the demo-app/ directory. The framework.precompiled/ and demo-app.precompiled/ directories will contain a version with all Lua files being byte-code pre-compiled, which can be used instead. You may copy these directories (with cp -L to follow links) to any other place you like. Use the files doc/lighttpd.sample.conf or doc/apache.sample.conf to setup your webserver appropriatly. Don't forget to setup a database, and make the tmp/ directory of the application writable for the web server process. Good luck and have fun! + After downloading the tar.gz package, unpack it, enter the unpacked directory and type make. If you use Mac OS X or if you experience problems during compilation, you need to edit the Makefile.options file prior to compilation. The framework itself will be available in the framework/ directory, while a demo application is available in the demo-app/ directory. The framework.precompiled/ and demo-app.precompiled/ directories will contain a version with all Lua files being byte-code pre-compiled, which can be used instead. You may copy these directories (with cp -L to follow links) to any other place you like. Don't forget to setup a database, and make the tmp/ directory of the application writable for the web server process. Good luck and have fun! +

Configuration, pre-fork and post-fork initializers

+ The Moonbridge Network Server creates forks (i.e. clones) of the application server process in order to handle concurrent requests. Certain initializations may be performed before forking, other initializations must be performed after forking. The application's configuration files as well as its pre-fork initializers are executed before forking. The application's post-fork initializers are executed after forking. In particular, any libraries that open file or network handles during initialization must not be loaded before the server process is forked. Opening database connections must be performed after forking as well. Execution order is as follows: +

+ Loading all WebMCP libraries except the "multirand" library (multirand opens /dev/urandom and thus must not be loaded prior to forking) +
+ Executing the selected configuration file: config/configuration_name.lua +
+ Executing all pre-fork initializers (both those in the app/_prefork/ and those in the app/application_name/_prefork/ directory) until call of execute.inner() within each initializer +
+ The Moonbridge Network Server forks the process (i.e. cloning the whole Lua machine)
+ Note: no file handles or network connections must be opened prior to this point! +
+ Executing all post-fork initializers (both those in the app/_postfork/ and those in the app/application_name/_postfork/ directory) until call of execute.inner() within each initializer +
+ For each request: +
- + Execution of all applicable filters until call of execute.inner() within each filter +
- + Handling of the request by calling the appropriate view or action +
- + Resuming execution of all filters in reverse order from that position where execute.inner() had been called +
+
+ Resuming execution of all post-fork initializers in reverse order from that position where execute.inner() had been called +
+ Resuming execution of all pre-fork initializers in reverse order from that position where execute.inner() had been called +

Using the atom library

@@ -97,23 +140,28 @@

Using the Object-Relational Mapper “mondelefant”

- The library “mondelefant” shipping with WebMCP can be used to access PostgreSQL databases. It also serves as an Object-Relational Mapper (ORM). Opening a connection to a database is usually done in a config file in the following way: + The library “mondelefant” shipping with WebMCP can be used to access PostgreSQL databases. It also serves as an Object-Relational Mapper (ORM). The database connection is usually configured in the config file (e.g. in config/devel.lua): +

+config.db = { engine="postgresql", dbname="webmcp_demo" }
+config.db_trace = true

+ In addition to configuring the database, it must be opened within a post-fork initializer (e.g. in app/_postfork/01_database.lua):

-db = assert( mondelefant.connect{ engine='postgresql', dbname='webmcp_demo' } )
-at_exit(function() 
-  db:close()
-end)
+_G.db = assert(mondelefant.connect(config.db))
 function mondelefant.class_prototype:get_db_conn() return db end
 
-function db:sql_tracer(command)
-  return function(error_info)
-    local error_info = error_info or {}
-    trace.sql{ command = command, error_position = error_info.position }
+if config.db_trace then
+  function db:sql_tracer(command)
+    return function(error_info)
+      local error_info = error_info or {}
+      trace.sql{ command = command, error_position = error_info.position }
+    end
   end
 end

- Overwriting the sql_tracer method of the database handle is optional, but helpful for debugging. The parameters for mondelefant.connect are directly passed to PostgreSQL's client library libpq. See PostgreSQL's documentation on PQconnect for information about supported parameters. + Overwriting the sql_tracer method of the database handle is optional, but helpful for debugging. The parameters for mondelefant.connect are directly passed to PostgreSQL's client library libpq. See PostgreSQL's documentation on PQconnect for information about supported parameters.

To define a model to be used within a WebMCP application, create a file named with the name of the model and .lua as extension in the model/ directory of your application. The most basic definition of a model (named “movie” in this example) is: @@ -165,15 +213,53 @@ app/

+ _prefork/ +
- + 10_first_prefork_initializer.lua +
- + 30_third_prefork_initializer.lua +
+
+ _postfork/ +
- + 01_first_postfork_initializer.lua +
- + 03_third_postfork_initializer.lua +
+
main/
- + _prefork/ +
  - + 20_second_prefork_initializer.lua +
  +
- + _postfork/ +
  - + 02_second_postfork_initializer.lua +
  +
- _filter/
  - 10_first_filter.lua +
  - -
  - …
+
Starting your application
+
+ Ensure that the moonbridge binary is within your system's search path and that the moonbridge_http.lua file is included in the LUA_PATH or linked into the framework's lib/ directory (alternatively the MOONBR_LUA_PATH option might be set accordingly at compile-time of the Moonbridge Network Server). To start an application, call the mcp.lua executable (found in framework/bin/mcp.lua) with the following arguments: +
+
1. + Path of the WebMCP framework directory, e.g. ./framework +
2. + Path of your application's directory, e.g. ./demo-app +
3. + Name of your applicaiton (usually main) +
4. + Name of configuration (e.g. devel to use config/devel.lua) +
Automatically generated reference for the WebMCP environment