Testing/Quickstart <- back | toc | forward -> Setting up the environment (and a hello world on the side)

Configuration

At the moment the methods to configure and start ucw are a bit under development. But things seem to be stabling out. The elegant production compliant way of starting ucw is by launching ucwctl, found in /path/to/ucw/bin/ucwctl. This will start your lisp as a deamon.

! --> (edit: uhum... well, stabling out... recently an array of people found the current setup to complicated, and probably the ucwctl way of starting ucw will be obliterated :D I'll just keep this in until it's clear what's gonna happen. See the last part of the next chapter to see a simpler way to get your application noticed.)

To let ucw find the proper configuration files, copy the files under /path/to/ucw/etc/ to either /your/home/.ucw or /etc/ucw.

Ucwctl depends on cl-launch, to which a number of ucwtl's configure options are passed. It provides a suite of launch options to invoke lisp from the command-line. Be sure to put a link to cl-launch somewhere in your application search path. For general cl-launch understanding, read the cl-launch documentation.

It's of course convenient to put ucwctl in the *nix executable search path but contrary to cl-launch it is not mandatory. Here's the configuration part of the ucwctl help output; -a, -c, -l, -k, -s and -t are passed to cl-launch:

-a, --asdf-root DIRECTORY   Register asdf search DIRECTORY
-c, --config-file FILE      Read FILE as config file.
-h, --help                  Display this help and exit.
-k, --stop-file FILE        Use FILE as stop file.
-l, --lisp NAME             Use NAME (without PATH) as Common Lisp
                            implementation.
    --log-root DIRECTORY    Save the logs in DIRECTORY, overriding the
                            --var-root option.
    --run-root DIRECTORY    Created pid/socket in DIRECTORY, overriding the
                            --var-root option.
-s, --start-file FILE       Use FILE as start file.
-t, --timeout SECONDS       Set timeout in SECONDS when trying to stop a
                            a running session.
-u, --ucwctl-file FILE      Read FILE as the ucwctl.conf file.
    --var-root DIRECTORY    Save the logs in DIRECTORU/log/ucw and create
                            pid/socket in DIRECTORY/run/ucw, if the two
                            options --log-root and --run-root are not set.
    

In /path/to/configdir/ucwctl.conf default values are provided except for the lisp implementation and the .asd directory. So at the least you'd want to change them to point to the proper lisp and dir, or just specify those on the commandline. If you want to specify different paths for --log-root and --run-root in your config file, add LOGROOT=/path/to/log-root and RUNROOT=/path/to/run-root, leaving VARROOT empty. If you run ucwctl as user and didn't change ucwctl or supplied different paths for log-root and run-root (which default to paths under /var) on the commandline, they will default to paths under /your/home/dir/var. You can also specify a different ucwctl.conf file instead of /path/to/config-dir.

To be clear this is the hierarchy of where ucwctl will pick its configuration from. Higher up the list will be chosen over lower on the list:

1) command line options
2) -u|--ucwctl-file (if specified, exit if it cannot be read)
3) ~/.ucw/ucwctl.conf (if it exists)
4) /etc/ucw/ucwctl.conf (if it exists)

A deeper discussion is available at:

http://common-lisp.net/pipermail/bese-devel/2006-April/001932.html
http://common-lisp.net/pipermail/bese-devel/2006-April/001961.html

Now you can start ucw by invoking:

ucwctl start
    

Without having configured anything (in /path/to/conf.lisp) this will start ucw with the built-in httpd server, just as with cl-launch. But now you have log files and more importantly you are not tied to a particular console. Point your browser at http://127.0.0.1:8080/ and hope for the best. Hook up slime through port 4005 if you also actually want to code something.

To stop ucw type:

ucwctl stop
    

To attach to a running ucw server type:

ucwctl attach
    

This calls attachtty, installed alongside detachtty, and passes attachy the socket, the path of which is defined in the ucwctl startup script. De-attach attachtty by giving it a sighup signal, eg by closing your terminal window or by pressing ctl-\. Note that you should be a bit careful when you attach to a socket and you start typing away at the repl. By default cl-launch will terminate the running process when the debugger is invoked. This behavior is changeable; check the cl-launch script (or not, someone on the mailing-list pointed out a bug).

To test if ucw works with your chosen backend open /path/to/conf.lisp (to be found in /etc/ucw/conf.lisp if you copied it from /path/to/ucw_dev/bin/etc/) and change:

(setf *ucw-backend-type* ':httpd)
(setf *ucw-backend-host* "127.0.0.1")
(setf *ucw-backend-port* 8080)
    

to:

(setf *ucw-backend-type* ':mod-lisp)
(setf *ucw-backend-host* "127.0.0.1")
(setf *ucw-backend-port* 3001)
    

or to:

(setf *ucw-backend-type* ':araneida)
(setf *ucw-backend-host* "127.0.0.1")
(setf *ucw-backend-port* 8080)
    

or to:

(setf *ucw-backend-type* ':aserve)
(setf *ucw-backend-host* "127.0.0.1")
(setf *ucw-backend-port* 8080)
    

Repeat your chosen startup procedure for ucwctl with th note that if you use mod_lisp you have to point your browser at http://127.0.0.1/path/you/specified/in/apache/this/link/goes/to/the/root/index.ucw, without the 8080 (defaults to the server root here).

note also that the default conf.lisp configuration defaults to the configuration in /path/to/ucw_dev/src/default.lisp which is the default configuration ;-) So if you don't change anything in conf.lisp you might just as well omit it.

The variables in conf.lisp that we didn't cover yet are:

(setf *ucw-swank-port* 4005)
    

- used to connect to emacs, et al.

(setf *ucw-server-class* 'standard-server)
    

- leave as is. I'm not even sure if there is a non-standard server we should be interested in.

(setf *ucw-inspector* t)
    

- let's you inspect ucw inside the html pages you made when set to t. Seeing is believing. Set to nil to see the page as normal.

(setf *ucw-debugger* t)
    

- sends debugging html to the client when set to t. Seeing is believing. Set to nil to not send debugging info to the client and to invoke the debugger in your editor.

(setf *ucw-log-level* '+INFO+)
    

- Sets the log-level threshold for the information that will be logged by the base ucw logger and which will be pumped to the ucw.log file. these are the log levels to choose from, together with their value:

+dribble+ = 0
+debug+ = 1
+info+ = 2
+warn+ = 3
+error+ = 4
+fatal+ = 5

So in our example debug info and dribble will not be logged to ucw.log.

(setf *ucw-applications-directory* "/etc/ucw/applications.d/")
    

- sets the applications directory, see next chapter

(setf *ucw-systems* '(:ucw.admin :ucw.examples))
(setf *ucw-applications* '(it.bese.ucw::*admin-application*
	   		       it.bese.ucw-user::*example-application*))
    

- supply ucw applications to load. See next chapter.

Testing/Quickstart <- back | toc | forward -> Setting up the environment (and a hello world on the side)