Complete Beginners Setup for Weblocks

(+ slime emacs sbcl (some linux paredit redshank))

Introduction

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

alt-F2

konsole

On a mac, use

Applications->Utilities->Terminal.app

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

Get emacs

sudo apt-get install emacs22

sudo apt-get install emacs-snapshot

Get sbcl

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.

wget http://prdownloads.sourceforge.net/sbcl/sbcl-1.0.17-x86-64-linux-binary.tar.bz2

tar -xvjf

http://prdownloads.sourceforge.net/sbcl/sbcl-1.0.17-x86-64-linux-binary.tar.bz2

Installation is simply going into the newly created sbcl directory, and type

sudo bash install.sh

Note: after this step is done, use

which sbcl

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

sbcl --version

Let's get slime.. this also creates the dir ~/slime for us.

cd ~/

cvs -d :pserver:anonymous:anonymous@common-lisp.net:/project/slime/cvsroot co slime

Emacs keystrokes

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/")

(default-directory my-lisp-dir))

(setq load-path (cons my-lisp-dir load-path))

(normal-top-level-add-subdirs-to-load-path)))

;this is where we'll put all our stuff

(require 'lisper)

EOF

Now make a directory to store our emacs elisp files:

mkdir ~/elisp

cd ~/elisp

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

(require 'w3m-e21)

(provide 'w3m-e23)



;we'll wget these later

(require 'cldoc)

(require 'paredit)

(require 'redshank)



;; testing

(provide 'lisper)



;;;; SLIME



;setting up slime and lisp

(add-to-list 'load-path "~/slime")

(add-to-list 'load-path "~/slime/contrib")

(require 'slime)

(slime-setup '(slime-fancy slime-asdf slime-tramp))

(add-hook 'slime-load-hook (lambda () (require 'slime-fuzzy)

(slime-fuzzy-init)))

(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")



;;from emacswiki

(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

browse-url-generic-program "elinks"

browse-url-generic-args '(""))



(defun my-slime-settings ()

(slime-mode t)

(turn-on-redshank-mode) ;ymmv is great and stays out of your way

;(paredit-mode) ;ymmv: is great and gets in your way

(customkeys)



;;; 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"



lisp-indent-function 'common-lisp-indent-function

slime-complete-symbol-function 'slime-fuzzy-complete-system

;;; set your own hyperspec path!!

common-lisp-hyperspec-root "file:///usr/share/doc/hyperspec/"

slime-startup-animation t))



(my-slime-settings)

;(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

(add-hook 'slime-repl-mode-hook

(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."

t)



;; snippet for Emacs interaction with lispdoc, by Bill Clementson

;; http://bc.tech.coop/blog/070515.html

(defun lispdoc ()

"Searches lispdoc.com for SYMBOL, which is by default the

symbol currently under the curser"

(interactive)

(let* ((word-at-point (word-at-point))

(symbol-at-point (symbol-at-point))

(default (symbol-name symbol-at-point))

(inp (read-from-minibuffer

(if (or word-at-point symbol-at-point)

(concat "Symbol (default " default "): ")

"Symbol (no default): "))))

(if (and (string= inp "")

(not word-at-point)

(not symbol-at-point))

(message "you didn't enter a symbol!")

(let ((search-type

(read-from-minibuffer

"full-text (f) or basic (b) search (default b)? ")))

(browse-url (concat "http://lispdoc.com?q="

(if (string= inp "")

default

inp)

"&search;="

(if (string-equal search-type "f")

"full+text+search"

"basic+search")))))))



EOF

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.
  
  
  



• Paths
  
  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..

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.

cd ~/elisp

# wget the actual url! or use your browser to dowload the files,

# but remember to copy them to ~/elisp

wget cldoc.el

wget paredit.el

wget redshank.el

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.



Elinks keys:

< 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.

#Run Terminal/Konsole/gnome-terminal

screen

emacs -nw

C-a C-c

elinks http://google.com

In screen

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!