(+ slime emacs sbcl (some linux paredit redshank))
This guide was written on ubuntu linux. Most of it should be the same on mac os x -- just adjust the pathnames and installers as necessary.
Win32 users should get lispbox at the gigamonkeys.com site and skip the initial setup: most of the weblocks stuff remains the same.
We start the instructions assuming you have installed your unix (linux or os x) and are logged into it. For those familiar with unix, you can skim through or go directly to the post titled Installing Weblocks.
The intent of this tutorial is to get beginners up and running with a functional development environment. It is hoped that by including some digressions on emacs, slime etc., at each step, by the end of the tutorial readers will be somewhat acquainted with the possibilities of this great system, and have a feel for what to do next.
Many thanks to Slava for a great framework and emacs wiki contributors for tips.
Start a Terminal
Start a terminal on KDE Ubuntu by typing
On a mac, use
The following instructions use sudo. Assuming it is setup (the default case on macs and ubuntu) just follow the instructions, otherwise, see below.
Obtaining Emacs and SBCL
In order to get started quickly, we'll kind of punt on the emacs installation: if you're on mac os x, google for aquamacs, or use fink/macports, or see here. For redhat and derivative linuxen use rpm to get the appropriate emacs packages.
See what's available:
apt-cache search emacs | more
sudo apt-get install emacs22
sudo apt-get install emacs-snapshot
sudo apt-get install sbcl
Or go to this sbcl page and download your choice of platform and version. Copy the download to a directory in /tmp and tar -xvjf it.
Installation is simply going into the newly created sbcl directory, and type
sudo bash install.sh
Note: after this step is done, use
and note down the pathnames for the binaries, we'll need them later.
If sudo does not work
Open a new terminal and type "su - root", then enter the root password, then type the sudo commands above. Use your original terminal for non sudo commands, and keep this one around for the sudo commands. Don't mix up the two terminals!
Setting up your home directory
We'll create a new user for our lisp hacking because it'll be easier to keep a clean ~/ that way, plus we can tar up ~/ for backups (or use git to put our setup on github.com)
Also it may make it easier to manage downloaded lisp packages.
Add the user
sudo adduser lisper
Become the user
su - lisper
Check sbcl version
Let's get slime.. this also creates the dir ~/slime for us.
cvs -d :pserver:anonymous:firstname.lastname@example.org:/project/slime/cvsroot co slime
Note that in emacs parlance C-d means control-d, M-d is meta-d (alt is usually the same as meta) and M-D is different from M-d (the first one needs the shift key). We'll try and use emacs keystroke chains from now on. See the emacs manual for help if necessary.
Setting up emacs
Create the following file using a text editor and save it as /home/lisper/.emacs.el -- if using linux you should be able to select all this text and middle click it into a terminal.
Also, read the comments in these files (comments start with ; for elisp) and note that ymmv paraphrases to "remove or edit this if things go wrong, and try again".
cat > .emacs.el << EOF
;make ~/elisp contain all our site lisp
(if (fboundp 'normal-top-level-add-subdirs-to-load-path)
(let* ((my-lisp-dir "~/elisp/")
(setq load-path (cons my-lisp-dir load-path))
;this is where we'll put all our stuff
Now make a directory to store our emacs elisp files:
Make our lisper file -- this is required by (require 'lisper) in .emacs.el above
cat > lisper.el << EOF
;kludge of the unknown hacker, ymmv
;found at http://www.emacswiki.org/cgi-bin/wiki/emacs-w3m#WThreeM
;we'll wget these later
;setting up slime and lisp
(add-to-list 'load-path "~/slime")
(add-to-list 'load-path "~/slime/contrib")
(slime-setup '(slime-fancy slime-asdf slime-tramp))
(add-hook 'slime-load-hook (lambda () (require 'slime-fuzzy)
(add-hook 'lisp-mode-hook 'my-slime-settings)
(global-set-key [C-o] 'other-window)
;;; set your own sbcl path!!
(setenv "SBCL_HOME" "/usr/local/lib/sbcl")
(defun customkeys ()
(local-set-key (kbd "TAB") 'slime-indent-and-complete-symbol) ;;mathrick#lisp
(local-set-key [C-tab] 'slime-fuzzy-complete-symbol)
(define-key lisp-mode-map (kbd "C-c l") 'lispdoc) ;billc lispdoc key
(local-set-key [return] 'newline-and-indent))
(setq browse-url-browser-function 'browse-url-generic
(defun my-slime-settings ()
(turn-on-redshank-mode) ;ymmv is great and stays out of your way
;(paredit-mode) ;ymmv: is great and gets in your way
;;; set your own sbcl path!!
#|no core|# (setq inferior-lisp-program "/usr/local/bin/sbcl --noinform --no-userinit"
; with no cores (setq inferior-lisp-program "/usr/local/bin/sbcl --noinform --no-userinit"
; rm'd cores (setq inferior-lisp-program "/usr/local/bin/sbcl --noinform --core /home/lisper/.sbcl/sbcl.core-blocks-and-swank --no-userinit"
; replace core
; #|current|# (setq inferior-lisp-program "/usr/local/bin/sbcl --noinform --core /home/lisper/.sbcl/sbcl.core --no-userinit"
;;; set your own hyperspec path!!
;(add-hook 'inferior-lisp-mode-hook (lambda () (inferior-slime-mode t)))
; TODO explain
(define-key global-map (kbd "") 'slime-selector)
;;two funcs for setting up enter and C-tab in diff slime windows
(lambda () (local-set-key [return] 'slime-repl-return)))
;; ymmv remove this if you want
(autoload 'paredit-mode "paredit"
"Minor mode for pseudo-structurally editing Lisp code."
;; snippet for Emacs interaction with lispdoc, by Bill Clementson
(defun lispdoc ()
"Searches lispdoc.com for SYMBOL, which is by default the
symbol currently under the curser"
(let* ((word-at-point (word-at-point))
(default (symbol-name symbol-at-point))
(if (or word-at-point symbol-at-point)
(concat "Symbol (default " default "): ")
"Symbol (no default): "))))
(if (and (string= inp "")
(message "you didn't enter a symbol!")
"full-text (f) or basic (b) search (default b)? ")))
(browse-url (concat "http://lispdoc.com?q="
(if (string= inp "")
(if (string-equal search-type "f")
Notes on lisper.el
- paredit, redshank:
paredit is an emacs mode that gives you ways to edit lisp forms instead of plaintext. It'll ensure your lisp code is always well-formed (in the Godel Escher Bach sense) but it'll be a pain in the neck and it's a joy to use. There are neat key-combos for moving along the s-expression tree, you can copy and delete entire forms by using C-k and C-y! Just make sure you keep a browser window with the cheatsheet open and refer to the handy diagram in the right column of the cheatsheet to figure out what keys you need to press. If you ever have trouble with it, M-x paredit-mode toggles it off.
You will need to adjust the paths in the file above, particularly all sbcl paths and the hyperspec path. The hyperspec can be installed with apt-get on linux, and we checked the sbcl path earlier.
Mac users: /home/janedoe translates to /Users/janedoe and depending on how you install sbcl it might go in /Applications or in /opt
F12 selector: when you've run slime (M-x slime, see below) you can use f12 to jump between the repl and the last lisp buffer you were editing.
f12 r -> jumps to repl
f12 l -> jumps to file
Continuing our setup, we now get cldoc, paredit and redshank to help us in emacs. The function "my-slime-settings" in lisper.el controls their functionality.
# wget the actual url! or use your browser to dowload the files,
# but remember to copy them to ~/elisp
Elinks and screen
Elinks is useful browser for quickly browsing lisp docs using Bill Clementson's elisp function, so we'll get it. Screen is a terminal utility that opens virtual windows inside a terminal. It's essential to use on a server, because if you get disconnected from your remote webserver it prevents your running programs from dying. When you're using screen, just ssh back into the server and use screen -rd to get your workspace back just as it was. It doesn't hurt to apt-get it even if you decide not to use it for now, so we'll add it to our apt-get command.
Note: other options are using a remote REPL and/or tramp in emacs to edit remote files over ssh.
apt-get install elinks screen
You'll have to perform some setup within elinks options to ensure that links open in a new tab. At the beginning of your emacs session you can open a single elinks browser (say in a new terminal or using the screen command) and then any search you do for lisp docs within emacs will pop up a window in that browser. Or you can use safari, konqueror or firefox (modify lisper.el above, for example, just put "konqueror" in place of the string "elinks").
To use billc's function, position the block cursor (recommended over underline!) on a lisp keyword and type C-c l -- emacs will ask you if you want a full search or basic search. Press enter. Go to your elinks or browser window to view the result page. Check the emacs wiki link above if it doesn't work.
< and > --> cycle tabs
t and w --> new tab and close
Workspace setup with screen
This is an optional setup, feel free to skip it. Run a terminal and type screen to get a single screen (press enter after the warning). Now run emacs -nw here, then C-a C-c to create a new screen, and open an elinks in that.
C-a C-a switches you back between two screens
C-a space cycles you though the existing screens
C-a k kills a screen
C-a d detaches screen
C-a r reattaches if you were inadvertently logged out
C-a " lists all the screens
That's all we need for now. Go to the next post to start installing weblocks!