[STUMP] howto setup CVS stumpwm with cmucl

[greg scott]

i thank Shawn Betts for creating stumpwm, and hope this doc helps
others get it running with minimal effort.

this howto is for a setup of CVS stumpwm, based on cmucl, clocc, and
asdf.

from earlier postings, it sounds like debian already has system
definitions for clx and port, so this howto will be of most use to
people who like the slackware or "linux from scratch" approach.

no howto is needed if you start with stumpwm-0.0.3.tar, but i assume
you want to keep up with stumpwm development, which means using CVS
stumpwm and dealing with the additional complexity of clocc and asdf.

download info is provided, and using versions specified there will
minimize troubleshooting. once you get it working, you can play with
other versions. some asdf download instructions i encountered were
wrong, so follow my instructions in the download section below.

overview
--------
it is assumed that startx will read .xinitrc, but you may be using
.xsession instead.

$MY_PATH is the part of the path that depends upon your installation
choices. for example, i keep asdf in ~/CVS/, so for me
"$MY_PATH/asdf/asdf" will expand to "/home/userid/CVS/asdf/asdf".  the
~ is fine in .xinitrc, but use the full path for entries in
~/.cmucl-init.lisp, ex. /home/your_userid/ rather than ~/.

steps to kick off cmucl, clocc, asdf: $MY_PATH/cmucl/bin/lisp will be
invoked in .xinitrc, and lisp will kick off what we need by processing
~/.cmucl-init.lisp.

you will create ~/.cmucl-init.lisp and add to it in stages. the final
version will appear at the end of this doc.


avoid confusion
---------------
the clx that comes with cmucl will be used, rather than the clx that
comes with clocc.

later you can play with the clocc clx, but for now keep it simple and
use the cmucl clx.


a gotcha
--------
stumpwm.asd has this for debian users:
:depends-on (:cmucl-clx :port)

as the readme says, for non-debian, this should be:
:depends-on (:clx :port)

the problem is that this assumes asdf system definitions for clx and
port, ie. clx.asd and port.asd must exist and be symlinked in the asdf
registry.  this may be true for debian, but not for all distros.

just comment out the line
:depends-on (:clx :port)
from stumpwm.asd.


download info
-------------
0. cmucl
ftp://ftp.common-lisp.net/pub/project/cmucl/release/19a/cmucl-19a-x86-linux.tar.bz2
ftp://ftp.common-lisp.net/pub/project/cmucl/release/19a/cmucl-19a-x86-linux.extra.tar.bz2
not immediately needed, but see also:
ftp://ftp.common-lisp.net/pub/project/cmucl/release/19a/patches/


for CVS, make sure you have done this:
export CVS_RSH="ssh"

1. stumpwm
cvs -z3 -d:ext:address@hidden:/cvsroot/stumpwm co stumpwm

2. asdf
cvs -d:pserver:address@hidden:/cvsroot/cclan login
(no password: just press Enter)
cvs -z3 -d:pserver:address@hidden:/cvsroot/cclan co -r RELEASE asdf

3. clocc
http://clocc.sourceforge.net/snapshot/clocc-11-10-04.tgz



installation notes
------------------
cmucl
-----
mkdir $MY_PATH/cmucl
mv both cmucl-19a-x86-linux.tar.bz2 and
cmucl-19a-x86-linux.extra.tar.bz2 there and unpack.
cmucl-19a-x86-linux.extra.tar will provide:
  lib/cmucl/lib/subsystems/clx-library.x86f
this is what will get loaded by the (require 'clx) in your
final version of ~/.cmucl-init.lisp
[there is a clocc clx ($MY_PATH/clocc/src/gui/clx/clx.lisp), but
we won't be using it.]


stumpwm
-------
just need to edit $MY_PATH/stumpwm/stumpwm.asd per instructions
in the section "a gotcha" above.



clocc
-----
you don't need to do anything except unpack
clocc-11-10-04.tgz, but you might as well try to
compile clocc now [ie. it is optional but advisable].

create a ~/.cmucl-init.lisp with only this:
(setq *clocc-root* "$MY_PATH/clocc/")
(load "$MY_PATH/clocc/clocc")

now run cmucl lisp, which will process ~/.cmucl-init.lisp:
$MY_PATH/cmucl/bin/lisp
at the lisp prompt, eval
(compile-file (concatenate 'string *clocc-root* "clocc"))

quit lisp after compiling clocc.lisp.

now add clocc port load info to ~/.cmucl-init.lisp, so it looks
like this:
(setq *clocc-root* "$MY_PATH/clocc/")
(load "$MY_PATH/clocc/clocc")

(load (translate-logical-pathname "clocc:src;port;ext"))
(load (translate-logical-pathname "clocc:src;port;gray"))
(load (translate-logical-pathname "clocc:src;port;net"))
;(load (translate-logical-pathname "clocc:src;port;path"))
(load (translate-logical-pathname "clocc:src;port;proc"))
(load (translate-logical-pathname "clocc:src;port;shell"))
;(load (translate-logical-pathname "clocc:src;port;sys"))

i commented out the path and sys entries, since they get loaded
anyway. uncomment them if there is cause for concern.



asdf
----
once you've got it via CVS, you just need to decide what
directory will serve as your asdf "registry". this is where
you put symlinks to the system definition files, such as
$MY_PATH/stumpwm/stumpwm.asd.


as usual, $MY_PATH is determined by your installation choices.
keep it simple by doing as the asdf README advises:
mkdir $MY_PATH/cl/systems
cd $MY_PATH/cl/systems
ln -s $MY_PATH/stumpwm/stumpwm.asd .


now add this to ~/.cmucl-init.lisp:
#-:asdf (load "$MY_PATH/asdf/asdf")
(pushnew "$MY_PATH/cl/systems/" asdf:*central-registry* :test #'equal)



let 'er rip
-----------
0. make the final version of ~/.cmucl-init.lisp
the additions are (require 'clx) and loading stumpwm.

the final ~/.cmucl-init.lisp should look like this, but with
substitution of all occurrences of $MY_PATH using full paths:

;; clocc section
(setq *clocc-root* "/home/gkscott/clocc/")
(load (concatenate 'string *clocc-root* "clocc"))

;; clocc port section
(load (translate-logical-pathname "clocc:src;port;ext"))
(load (translate-logical-pathname "clocc:src;port;gray"))
(load (translate-logical-pathname "clocc:src;port;net"))
;(load (translate-logical-pathname "clocc:src;port;path"))
(load (translate-logical-pathname "clocc:src;port;proc"))
(load (translate-logical-pathname "clocc:src;port;shell"))
;(load (translate-logical-pathname "clocc:src;port;sys"))

;; asdf section
#-:asdf (load "$MY_PATH/asdf/asdf")
(pushnew "$MY_PATH/cl/systems/" asdf:*central-registry* :test #'equal)

;; clx section
(require 'clx)

;; stumpwm section
(asdf:operate 'asdf:load-op 'stumpwm)
(stumpwm:stumpwm)


1. in .xinitrc (or .xsession), comment out the part where you
launch your regular wm, and add this:
  $MY_PATH/cmucl/bin/lisp


2. startx
lisp will be invoked by step 1, and will process ~/.cmucl-init.lisp,
which will load clocc and asdf; the (require 'clx) will use cmucl's
clx, and then asdf will start stumpwm.

3. after you see the stumpwm welcome message, do "C-t !" and then
emacs <CR>.

the first time you startx, compilation of stumpwm files may delay the
stumpwm welcome message (30 secs on my old box). if your patience
wears thin, C-A-F1 (virtual console) to see if you got dropped into
the debugger.


pre-loading slime
-----------------
if you use slime, i would follow the excellent suggestion from
Manuel Giraud and put this at the top of your ~/.cmucl-init.lisp,
again using full-path expansion of $MY_PATH:

;; load SLIME
(load #p"$MY_PATH/.slime/fasl/cmu-19a/nregex.x86f")
(load #p"$MY_PATH/.slime/fasl/cmu-19a/swank-backend.x86f")
(load #p"$MY_PATH/.slime/fasl/cmu-19a/swank.x86f")
(load #p"$MY_PATH/.slime/fasl/cmu-19a/swank-cmucl.x86f")
(load #p"$MY_PATH/.slime/fasl/cmu-19a/swank-source-path-parser.x86f")

(swank:create-swank-server 4005 :spawn)

after launching emacs in stumpwm, M-x slime-connect and accept defaults.
then you can play in the REPL buffer.


one last thing
--------------
something useful you can do in the REPL buffer is compile defsystem
and port files. this is based on the clocc INSTALL file.

CL-USER> (compile-file (translate-logical-pathname 
"clocc:src;defsystem;defsystem"))
CL-USER> (load *)
CL-USER> (mk:add-registry-location (translate-logical-pathname 
"clocc:src;port;"))
CL-USER> (mk:oos "port" :compile)

later, you can make defsystem available within cmucl:
mv $MY_PATH/clocc/src/defsystem-3.x/defsystem.x86f 
$MY_PATH/cmucl/lib/cmucl/lib/subsystems/defsystem-library.x86f

note that defsystem.x86f is renamed to defsystem-library.x86f

and if the garbage collection messages bother you, add this to 
~/.cmucl-init.lisp:
(setq ext:*gc-verbose* nil)


-- 
greg scott