[Openmcl-devel] Docs 2.2 and 2.5 draft

[Hamilton Link]

Well it took me a while to get to it since I proposed it be done, but...

Here's some updated documentation. I think possibly this section 2.2.  
should be 2.1, and "obtaining etc. from cvs" should be 2.2 instead. I  
just tested all of this, except for going through the firewall (which  
works, I just am not set up for it at home).

h

2.2.  What you need, and where to get it.

In general, tracking the latest sources of openmcl is the right thing  
to do if you are using some of the more experimental features, such as  
the budding IDE or the ObjC bridge, or are doing "fringe" lisp  
development where you might find and need up-to-date fixes for bugs. It  
should be relatively easy to do if you have some familiarity with CVS  
and are comfortable working at a unix command prompt.

When building openmcl from scratch, several subcomponents must  
initially be separately downloaded and unpacked. Once this is done,  
keeping openmcl up to date requires ensuring that these same components  
are kept up to date. The minimum set of components is:

  - The latest source code
  - An openmcl "lisp image"
  - The FFI "interface database"

The running examples in this section assume installation in  
/Applications/openmcl/ccl under Mac OS X. I use Safari, and my  
downloads directory is ~/temp.

To build the stable 0.14 version, read sections 2.2.1.--2.2.3.
For the bleeding-edge 0.14-dev version, see section 2.2.4. as well.
If you have to go through a firewall, see section 2.2.5. as well.

If you are impatient and have everything, read 2.2.6. (instead of  
sections 2.3--2.5)

2.2.1.  Source code

Given CVS access, the latest source code may be checked out from one of  
the repositories (see Section 2.1). A reasonably current version can  
also be unpacked from a source archive downloaded via Section 4. of the  
<a  
href=http://openmcl.clozure.com/Distributions/ 
index.html>distributions</a> page. Both of these paths should result in  
a ccl directory being created (I personally keep this directory within  
/Applications/openmcl under Mac OS X).

My preferred path is to download a source archive. This has CVS working  
copy information in it and can be brought up to date with the CVS  
repository by running 'cvs update':

  - Using Safari, I go to the openmcl website, to the Distributions  
page, to the most recent Release, and download the source archive using  
http.
  - In a terminal,
    cd /Applications/openmcl
    tar xvzf ~/temp/openmcl-darwinppc-bin-0.14.2-p1.tar.gz
    cd ccl
    cvs up

2.2.2.  A lisp image

The lisp kernel can be built from scratch with nothing but the openmcl  
sources. However, building a lisp image (by compiling lisp code)  
requires a lisp image. The most commonly used source of a lisp image  
will be the binary distribution of lisp:

  - Using Safari, I go to the openmcl website, to the Distributions  
page, to the most recent Release, and download the binary archive for  
Mac OS X using http.
  - In a terminal,
    cd /Applications/openmcl
    tar xvzf ~/temp/openmcl-src-0.14.2-p1.tar.gz

This has the happy side effect of installing some documentation (this  
is not currently the same as the web site documentation).

2.2.3.  The interface database.

After unpacking a binary distribution and the sources, it is possible  
to run openmcl, BUT you may get mysterious errors if the binary  
distribution does not contain the latest interface database (remember  
that the binary distribution does not represent the latest sources, it  
is only obtained to facilitate building the latest sources!).

When building openmcl from scratch, it is recommended that you ensure  
you have the latest interface databases.

  - Using Safari, I go to the openmcl website, to the Distributions  
page, to the most recent Release, and download the interface database  
(in section 2. of that page, "Interface database issues") for Mac OS X  
using http.
  - In a terminal,
    cd /Applications/openmcl
    tar xvzf ~/temp/openmcl-darwin-interfaces-040505.tar.gz

2.2.4.  Living on the edge.

The bleeding edge of development is usually reasonably stable and  
usually just as easy to bootstrap. It is where several useful bits of  
functionality live that are relatively new, such as the ObjC bridge and  
the IDE (see section 2.5).

The same three pieces are needed for the bleeding edge as for the  
stable version, obtaining the first two of those pieces (sources and  
images) can require a little more attention.

2.2.4.1.  Bleeding-edge sources.

The way to get the bleeding-edge sources is via CVS (the 0.14 source  
distributions are archives of the stable branch).

  - In the termainal,
    cd /Applications/openmcl
    cvs -d :pserver:cvs at clozure.com:/usr/local/tmpcvs/ccl-0.14-dev co ccl

2.2.4.2.  Bleeding-edge images.

Normally, the binary distribution image can be used to bootstrap the  
bleeding edge sources. When certain modifications to lisp are made, in  
particular when changes are made that are both deep enough within lisp  
to make bootstrapping difficult, and and experimental enough to be  
inappropriate for a published release, an image is distributed in  
isolation.

Such images are made available at ftp://clozure.com/pub/testing/, have  
been named dppccl-image-yymmdd.tar.gz, and contain a ccl directory with  
a single dppccl.image file in them (so they may be unpacked in  
/Applications/openmcl as are the other distributions.

2.2.5.  Punching through a firewall (CVS access via ssh).

(I'm not entirely sure this is 100% correct, I'll try to double-check  
it against my configuration when I'm on a machine configured thusly and  
email a new 2.2.5 at some point -- until then, caveat emptor and RTFM  
when setting up your own system)

If you're like many of us, you work behind a firewall that does not  
allow traffic through on very many ports. You can try to get the  
firewall changed, but it's probably easier if you just get ssh access.

< GB, where do people go to get sshcvs at clozure.com and config files for  
their .ssh directory? >

In your ~/.tcshrc file (for example -- if you use a different shell  
then you know enough to translate this), add
CVS_RSH=ssh

Then connect to the repository and check out the sources (note the  
example is to obtain the stable version of 0.14).
  - In the terminal,
    cd /Applications/openmcl
    cvs -d :ext:sshcvs at clozure.com:/usr/local/tmpcvs/ccl-0.14 co ccl

2.2.6.  Building everything, for the impatient.

Given that you now have everything you need, do the following steps to  
bring your lisp system completely up to date.
  - In a terminal,
    cd /Applications/openmcl/ccl/lisp-kernel/darwin
    make clean ; make
    cd /Applications/openmcl/ccl
    openmcl
  - In openmcl,
    (xload-level-0)
    (compile-ccl)
    (quit)
  - In the terminal,
    cd /Applications/openmcl/ccl
    ./dppccl ppc-boot.image
  - In the bootstrapping version of openmcl,
    (save-application "dppccl.image")
You should now have updated everything, and can run openmcl as you were  
before, using the new kernel and image.

To also build the IDE,
  - In a terminal,
    openmcl
  - In openmcl,
    (require "COMPILE-HEMLOCK")
    (ccl::compile-hemlock)
    (quit)
When you restart lisp you will be able to (require "COCOA") to load the  
IDE.


2.5.  Building the IDE

Thanks to the ObjC bridge that makes it relatively easy to invoke and  
specialize Cocoa functionality from lisp, openmcl has a budding  
integrated development environment. It is very experimental and not  
entirely stable, and you need to track the 0.14-dev CVS tree if you  
plan to build and use it (see Section 2.2.5.).

After ensuring that you are running the latest bleeding-edge openmcl  
sources, what remains is to build the IDE is to compile Hemlock, the  
common-lisp cousin of emacs.
  - In a terminal,
    openmcl
  - In openmcl,
    (require "COMPILE-HEMLOCK")
    (ccl::compile-hemlock)
    (quit)
When you restart lisp you will be able to (require "COCOA") to load the  
IDE.

Yes, it's pretty simple. I expect that this section may evolve to  
include links to actually using the IDE and Hemlock (such as the two  
known Hemlock docs, the user's guide and the command implementer's  
guide), special instructions for getting additional bits from other  
people (such as the hyperspec for local use, and configuring hemlock to  
use a local copy of the openmcl web docs and hyperspec), that sort of  
thing.