OpenMCL Code

Introduction

This is a collection of code for OpenMCL.

OpenMCL is a open source Common Lisp implementation for Mac OS X (Darwin) and LinuxPPC. You can learn more about OpenMCL on http://openmcl.clozure.com/

This code was written by Sven Van Caekenberghe.

Distribution

You can download this software from my homepage at http://homepage.mac.com/svc/openmcl/openmcl.tgz. This code is also meant to be included as examples in the OpenMCL the distribution.

All software and documentation is Copyright (C) 2003 Sven Van Caekenberghe. You are granted the rights to distribute and use this software as governed by the terms of the Lisp Lesser GNU Public License (see http://opensource.franz.com/preamble.html), also known as the LLGPL.

There are currently two independent files in this package:

Installation

Basically, you load each file as needed ;-)

Usage

Remote Read-Eval-Print-Loop (REPL)

This is a remote read-eval-print-loop (REPL) server for OpenMCL. After you load this code in a lisp image and start the server, you can connect to the lisp image from the outside and start a read-eval-print-loop (REPL). This is a very powerful feature: it allows you to examine, debug, modify, patch or extend your application while it is running. In a shell you could test this as follows: openmcl -l remote-repl -e '(remote-repl:server)' This won't return or print anything. If you want you can put this in the background and use nohup. Next you can use telnet (any code that can read and write lines to and from a socket will do) as follows:

telnet 127.0.0.1 24365
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
Welcome to OpenMCL Version (Beta: Darwin) 0.13.2!
? *current-process*
#<PROCESS remote-repl(4) [Running] #x55D792E>
? *all-processes*
(#<PROCESS remote-repl(4) [Running] #x55D792E> 
 #<PROCESS external-process-watchdog(1) [Suspended] #x55BA356> 
 #<PROCESS Initial(0) [input-wait] #x517511E>)
? foo
> Error in process remote-repl(2): Unbound variable: FOO
> While executing: "Unknown"
> Type :GO to continue, :POP to abort.
> If continued: Retry getting the value of FOO.
Type :? for other options.
1 > :pop
? (setf foo 100)
100
? (remote-repl:exit)
Connection closed by foreign host.

As you can see, the remote REPL looks and feels just like the real OpenMCL toplevel (thanks to a very useful interal function ccl::make-mcl-listener-process that Gary Byers told me about). Multiple, independent connections can be made to the same lisp image. Note they are sharing state:

telnet 127.0.0.1 24365
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
Welcome to OpenMCL Version (Beta: Darwin) 0.13.2!
? *current-process*
#<PROCESS remote-repl(5) [Running] #x55DB306>
? foo
100
? (remote-repl:exit)
Connection closed by foreign host.

Closing a connection is best done by killing the current process, as in (process-kill *current-process*). The exit function is a shortcut for this. When a listener process hangs or is somehow lost, you could try opening a second connection and killing the process. Interrupting the toplevel using ctrl-c is currently not supported.

Take a moment to reflect upon the power this gives you. And with this power comes responsability. Typing (quit) by accident will kill your running lisp image. But there are millions of other ways to do harm. Therefore, only local connections are allowed by default. You have to be on the same host to be able to connect. Use ssh to login to the host in a secure way or ssh port forwarding to export this functionality to remote sites in a secure way.

Remote REPL API

The Remote REPL API is can be found here.

LispDoc

LispDoc is a tool (probably somewhat OpenMCL specific) that automatically generates documentation for all symbols exported from one or more packages, assuming that they have proper documentation strings. LispDoc tries to find the following information about a symbol:

If an exported symbol has no documentation, it is marked as undocumented to help you complete the documentation. It is often necessary to explicitely setf some documentation type for a symbol (like for automatically generated accessors of CLOS objects).

LispDoc operates in two phases: first documentation is gathered and an sexp representing the documentation is returned, next this representation can be rendered into HTML. If you are just interested in HTML files, you can do (lispdoc:lispdoc-html "/tmp/" :package1 :package2 :package3) and if all goes well, your documentation will be in the files /tmp/PACKAGE1.html /tmp/PACKAGE2.html /tmp/PACKAGE3.html respectively.

LispDoc API

The LispDoc API is can be found here.


$Id: readme.html,v 1.7 2004/01/13 10:18:49 sven Exp $