[kpax-devel] Installing KPAX

[Sven Van Caekenberghe]

Installing KPAX

The KPAX Common Lisp Web Application Framework is open-source  
software, licensed under the LLGPL. All other packages that KPAX  
depends on (cl-who, puri, s-utils, s-sysdeps, s-base64 and one or  
both of s-http-server and aserver, as well as all packages that these  
depends on) are also open-source. This means that you have to first  
obtain their source code, compile it and finally load it.

In order to manage compilation and load order of individual files, as  
well as compilation and load order of whole packages, KPAX and all  
its dependencies, are using ASDF. This means that compilation and  
loading are very easy, once things are set up properly.

KPAX allows you to write web applications that can be deployed in  
three different contexts:
  - behind apache using mod_lisp
  - behind portable allegro server
  - standalone using s-http-server
KPAX strictly separates static from dynamic content. In the first  
context, apache handles static content directly, while dynamic  
content goes through mod_lisp that passes it to your common lisp  
system - this is the preferred production setup. In the second and  
third context, both the static and the dynamic content are handled by  
your common lisp system - might be easier during development and is  
certainly easier

There is one internal ASDF system called kpax-core that contains most  
of the framework's code but none of the execution contexts. Three  
ASDF systems corresponding to each of the three contexts, called kpax- 
mod-lisp, kpax-paserve and kpax-s-http-server, allow you to load only  
the code you really need. The main ASDF system called kpax simply  
loads both the kpax-mod-lisp and kpax-s-http-server systems.

If necessary, please refer to the documentation and tutorials for  
ASDF, ASDF-INSTALL and ASDF-UPGRADE first.

The simplest and most end user friendly way to install KPAX is to use  
ASDF-INSTALL and ASDF-UPGRADE. Provided your common lisp  
implementation already knows about ASDF (or you have configured it to  
load ASDF automatically) and have at least configured the systems  
ASDF-INSTALL and ASDF-UPGRADE, you can do as follows:

CL-USER 1 > (asdf:operate 'asdf:load-op :asdf-install)
...
CL-USER 2 > (asdf-install:install :kpax)
...

And you're done! In subsequent runs, you no longer have to install  
KPAX and can just load it:

CL-USER 1 > (asdf:operate 'asdf:load-op :asdf-install)
...
CL-USER 2 > (asdf:operate 'asdf:load-op :kpax)
...

To check for newer versions, use ASDF-UPGRADE:

CL-USER 1 > (asdf:operate 'asdf:load-op :asdf-upgrade)
...
CL-USER 2 > (asdf-upgrade:report)
...
CL-USER 2 > (asdf-upgrade:upgrade)
...

Alternatively, you could manually download each package linking your  
asdf systems manually as you go. Both of the above approaches only  
deal with released (or packaged) versions of each package. You could  
also opt to retrieve one or more packages from their source code  
repositories (CVS, Subversion or DARCS). This might give you earlier  
access to patches but might be less stable (you however have manual  
control over which packages you want to upgrade).

The KPAX source code is in a DARCS repository. To retrieve the source  
tree, do:

$ darcs get http://www.beta9.be/darcs/kpax

Subsequently, you can keep up to date by doing:

$ darcs pull

inside the kpax directory.


Sven

PS: All feedback is welcome.

--
Sven Van Caekenberghe - http://homepage.mac.com/svc
Beta Nine - software engineering - http://www.beta9.be

"Lisp isn't a language, it's a building material." - Alan Kay