doc/readme.lml

   1 ;;; -*- Mode: Lisp -*-
   2
   3 (in-package #:lml2)
   4
   5 (html-file-page ("readme")
   6   (html
   7    (:head
   8     (:title "cl-modlisp readme")
   9     ((:meta :http-equiv "Content-Type" :content "text/html; charset=iso-8859-1"))
  10     ((:meta :name "Copyright" :content "Kevin Rosenberg 2002 <kevin@rosenberg.net>"))
  11     ((:meta :name "description" :content "cl-modlisp documentation"))
  12     ((:meta :name "author" :content "Kevin Rosenberg"))
  13     ((:meta :name "keywords" :content "Common Lisp, mod_lisp, cl-modlisp, apache")))
  14
  15    (:body
  16     (:h1 "cl-modlisp Documentation")
  17     (:h2 "Overview")
  18     (:p
  19      "cl-modlisp provides the Lisp side of the interface to Marc Battyani's mod_lisp apache module ("
  20      ((:a :href "http://www.fractalconcept.com") "http://www.fractalconcept.com")
  21      ").")
  22     (:h2 "Features")
  23     (:ul
  24      (:li "support for AllegroCL, CMUCL, SBCL with sb-thread, and Lispworks.")
  25      (:li "listener and worker socket/process management so that shutting down the listener closes all related open sockets and terminates all related proceses.")
  26      (:li "support for running multiple command processors on multiple ports.")
  27      (:li "transparent support for precomputing the HTML or XML response to take advantage of HTTP/1.1's Keep-Alive feature. This is switchable with a single keyword argument to the macro "
  28          (:tt "with-ml-page")
  29          ".")
  30      (:li "Optional timeout of worker processes")
  31      (:li "Two process models for flexibility")
  32      (:li "Demonstration processor included"))
  33     (:h2 "Prerequisites")
  34     (:ul
  35      (:li "Apache 1.3.x")
  36      (:li "mod_lisp apache module ("
  37          ((:a :href "http://www.fractalconcept.com")
  38            "http://www.fractalconcept.com")
  39          ").")
  40      (:li "kmrcl library ("
  41          ((:a :href "http://files.kpe.io/kmrcl")
  42            "http://files.kpe.io/kmrcl")
  43          ").")
  44      (:li "asdf ("
  45          ((:a :href "http://www.sf.net/projects/cclan")
  46            "http://www.sf.net/projects/cclan")
  47          ")."))
  48
  49     (:h2 "Supported Platforms")
  50     (:ul
  51      (:li "Allegro v6.2")
  52      (:li "CMUCL 18e")
  53      (:li "Lispworks v4.2")
  54      (:li "SBCL 0.8.1 with sb-thread (multi-threading)"))
  55
  56     (:h2 "Quickstart")
  57     (:ul
  58      (:li "The easiest way to install is to use the Debian GNU/Linux operating system. Using the testing or unstable distributions, you can give the command:"
  59      (:div
  60       (:tt "apt-get install libapache-mod-lisp cl-modlisp cl-kmrcl"))
  61      (:div
  62       "If you are not using Debian, you will need to download and install
  63 mod_lisp, cl-modlisp, and cl-kmrcl manually."))
  64      (:li
  65       "Add something like the below to httpd.conf and then restart apache"
  66       (:div (:tt "LispServer 127.0.0.1 20123 \"localhost\""))
  67       (:div (:tt "AddHandler lisp-handler .lsp")))
  68      (:li
  69       "Start your Lisp implementation and load cl-modlisp with"
  70       (:div (:tt "(asdf:operate 'asdf:load-op 'modlisp)")))
  71      (:li
  72       "Start the server with"
  73       (:div (:tt "(ml:modlisp-start :port 20123)")))
  74      (:li "Try some demostration pages"
  75           (:div (:tt "links http://localhost/fixed.lsp"))
  76           (:div (:tt "links http://localhost/debug.lsp")))
  77      (:li "Shutdown the all cl-modlisp servers with"
  78           (:div (:tt "(ml:modlisp-stop-all)"))))
  79
  80     (:h2 "Process Models")
  81     (:p "There are two process models")
  82     (:ul
  83      (:li (:div (:b "Each connection spawns a new thread"))
  84           (:div "This is the default model. Each new connection to listener socket spawns a new connection. This allows for an arbitrary number of concurrent connections. This has advantages if the workers require a long execution time."))
  85      (:li (:div (:b "Fixed pool of workers"))
  86           (:div "This model is selected by passing the number of worker processes to "
  87               (:tt "init/listener")
  88               " with the keyword "
  89               (:tt "number-fixed-workers")
  90               ". This model has a lower overhead since new processes are not created and destroyed with each connection. It has advantages when the workers have a short execution time.")))
  91
  92     (:h2 "Usage")
  93     (:p "The demo.lisp file for examples of using cl-modlisp.")
  94     )
  95
  96
  97  (:ul)
  98  (:li (:div (:strong "Overview"))
  99       (:div "cl-modlisp is a multi-threaded handler for HTTP requests forwarded by Marc Battyani's (http://www.fractalconcept.com) mod_lisp Apache module."))
 100  (:li (:div (:strong "Design Goals"))
 101       (:div "cl-modlisp is designed as a thin layer to dispatch a mod_lisp request with multi-platform compatibility. Currently, cl-modlisp supports SBCL [multithreaded], CMUCL, AllegroCL, and Lispworks."))
 102  (:li (:div (:strong "Dispatch model"))
 103       (:div "Extremely simple: All requests are forwarded to a single processor that is passed as a parameter to cl-modlisp's start-up function."))
 104  (:li (:div (:strong "Configuration"))
 105       (:div "All configuration is set by passing keyword arguments to
 106 modlisp-start")
 107       (:ul
 108        (:li "port number - a number")
 109        (:li "processor - function designator which will receive all requests")
 110        (:li "processor-args - list of extra arguments to be passed to processor")
 111        (:li "timeout - NIL means never timeout otherwise number of seconds")
 112        (:li "catch-errors - non-NIL means to catch errors")
 113        (:li "number-fixed-workers - NIL means to spawn a new worker process for each request")
 114        (:li "remote-host-checker - optional function designator to check the remote host IP address. Used for filtering requests.")))
 115  (:li (:div (:strong "Processor function"))
 116       (:div
 117 "This function receives an argument of the 'command' alist and any
 118 other arguments passed to modlisp-start as the :processor-args.  The
 119 'command' alist is an associative list of keys and values received
 120 from modlisp. No preprocessing is done except that keys are converted
 121 from strings to keywords forced to the default implementation case."))
 122  (:li (:div (:strong "Default Processor"))
 123       (:div "The default processor is a simple demo command processor not intended for end-user."))
 124  (:li (:div "URI Processing")
 125       (:div "None. The raw URL is the value of the :url key in the command alist."))
 126  (:li (:div "Responses")
 127       (:div "Responses are written to modlisp:*modlisp-socket*. The raw HTTP/1.1 header needs to be generated by the application."))
 128  (:li (:div "Utility functions")
 129       (:div "A few utility functions are provided")
 130       (:ul
 131        (:li (:div "with-ml-page")
 132             (:div "Outputs the body of the macro along with the HTTP/1.1 headers. Supports both precomputing responses with keep-alive connections and also outputing response to socket as it is generated. The latter is useful for lengthye reponses in time or length. Also support setting the content-type (default \"text/html\") and arbitrary list of headers."))
 133        (:li (:div "query-to-alist")
 134             (:div "Converts posted query to an alist. Doesn't handle multipart forms."))
 135        (:li (:div "redirect-to-location"))))
 136  (:li (:div (:strong "Known issues"))
 137       (:ul
 138        (:li "This application has been most tested on AllegroCL.")
 139        (:li
 140 (:p "By design, is not practical an application platform. It is should have
 141 an API package wrapped around this library which supports useful
 142 features like processing URIs, dispatches, cookies, and querys [URI
 143 and single/multipart POSTs]")
 144 (:p
 145 "Rather than adding these features to cl-modlisp, I've been working on
 146 a library which uses a session-id and dispatch model based on Franz's
 147 webactions library. It also integrates my portable version of Franz's
 148 URI module and adds query processing similar on AllegroServer's
 149 request-query functions. This library can used with both cl-modlisp
 150 and AllegroServe as connectors. However, as this library has grown, it
 151 looks more and more like AllegroServe, I've begun to question the
 152 value of using this library compared to just using Portable
 153 AllegroServe with just my webactions-like session-id and dispatch
 154 processors. In my mind, the greatest advantage of using this library
 155 is that it is a much smaller task maintaining cross-implementation
 156 compatibility with the cl-modlisp connector version maintaining such
 157 compatibility with paserve. The disadvantage of this library is that I
 158 dislike cloning AllegroServe's query and cookie processing. I do so,
 159 though, because I think their API is quite reasonable.  This library
 160 is currently driving http://umlisp.kpe.io/")
 161 )))))
 162
 163
 164
 165