Centrifugal

University California Berkeley (UCB) provides basic instructions for setting up UCB Scheme and Emacs, but this article goes into further details setting up for Mac OS X, my primary operating system. If anyone has a similar article for PCs, let me know and I will link to it.

This article is especially helpful to those who have a Mac and are taking the UC Berkeley CS 3 and CS 61 series—however, anyone who wants to expirement or learn with UCB Scheme may find this information helpful too. Essentially, the objective is to edit and compile Scheme in an environment similar to the UCB lab, utilizing Emacs and the appropriate STk libraries. First, I will outline how to SSH to the lab (you need to be enrolled in a class to have SSH access, contact your instructor for details). You do not need access to the lab to run UCB Scheme; this simply demonstrates how UCB Scheme—what we will emulate—operates on the UC Berkeley servers. Second, I will outline how to install the STk libraries. Third, I’ll give the gist on installing a versatile, useful, and friendly Emacs editor. You may also find Brian Harvey’s and Mathew Wright’s book, Simply Scheme: Introducing Computer Science, very useful.

By the way, this article assumes a basic knowledge of Mac OS X and Unix. Also worth noting, I’m operating on Mac OS X 10.5.7.

Update: Emacs may not work the same under OS 10.6; there appears to be issues with the buffer, operating Emacs via the terminal, and creating new files with Carbon Emacs. Anna provides a work-around in comment 8; I successfully tested it in Carbon Emacs on OS 10.6.7. Thanks to Jesse for pointing out the problem and Anna for coming up with a work-around. With that said, any help to restore Emacs to the same working order as under 10.5 is greatly appreciated!

So here are the parts:

SSH To Compare & Contrast
Installing STk Libraries
Installing Emacs
Links & Resources

SSH To Compare & Contrast

The UCB Emac environment is directly accessible on campus servers through SSH, and this serves as a source to compare and contrast where you’re at to where you should be. SSH access is not needed for setting up your local UCB Scheme environment, but it is helpful and will certainly be needed to submit homework. You will need to an account to access the server, these are typically handed out during the first lab class. If you are not a student and don’t have server access, this section demonstrates a few details of the UCB lab environment. Here are the steps for using SSH:

1. You will need X11 installed in Mac OS X, X11 displays the Emacs application from the remote server. I am running OS X 10.5.7, and X11 was already installed. You can check and see if X11 is installed on your computer by browsing to “Applications/Utilities” and locating the application. If X11 is not in there, visit the following link and scoll down to the “Graphics Mode Section,” installing X11.
2. I believe the server is changed from time to time, so ask your instructor or teacher assistant for the current server if necessary. In this example the server is “nova.” Assuming the server is Nova, enter the following in your terminal application:

   ssh -X cs61a-dv@nova.cs.berkeley.edu

3. The server will prompt you for a password, so proceed with a password provided during your lab. Note, your password will not appear as you type, so type carefully.
4. You should see a collection of stuff about your server, similar to this:
   
5. Now we’ll enter in a command to open a Scheme file in the UCB Emacs environment and run a few basic tests exemplifying what we want to simulate at home. So, in the server command line prompt, create a new file named “testbf.scm” in Emacs by entering:

   emacs testbf.scm &

   It will take some time…and a little more time…and some more time before Emacs opens next to your terminal, similar to this:

   

6. Now click the “File” menu in the Emacs window and select “Save” (there are shortcuts, but I will keep it point and click for the most part). This will save the file in your folder on the UCB server. You want proof? Go back to the terminal application and enter the command “ls” to list the files. You will see a file titled “testbf.scm” in your home directory. The “.scm” in the file name is important; it tells Emacs how to interact with the code in the file, i.e., by automatically coloring and indenting it.
7. Next, lets create a simple file demonstrating some key details of the UCB Emacs environment and UCB Scheme. In the top window of the Emacs application type the following code and then save your file:

   (define (testbf wd)
     (bf wd))
   

   This will appear in your Emacs window as such:
   

   Notice, as you typed the color and indents are automatically implemented. The indents are a key attribute unique to the USB Emac environment. Later we’ll do some edits to a file tilted “simply.emacs,” giving our local Emac application similar features to UCB’s.

   Also note, the function/procedure “testbf” will be used to test the UCB STk Simply library, where functions such as “bf” are available. The “bf” function returns every letter of the word but the first. If this call isn’t working in the STk commands, then the stk-simply library is not installed. So let’s go ahead and run this function in the STk.

8. While in the “testbf” window, use the “command s” shortcut. The window will split opening another window welcoming you to STk:

   

   Now type the following line of code to load “testbf” into the STk and press enter:

   (load “testbf”)

9. The STk will say OK, so lets run the function on the word apple. Type the following code into the STk:

   (testbf ‘apple)
   …and the result should be “pple,” outputting everything but the first letter:
   

That outlines the basic process of opening and running a file, giving us the key elements we need to simulate UCB’s editing environment, i.e., an STk that runs the UCB’s libraries—tested with the “bf” function—and an Emacs that indents and acts as UCB’s does.

Installing STk libraries

Installing the libraries was substantially easier than I thought, especially after being intimidated by another student’s comment on how the difficulty subdued his installation altogether. However, I had little trouble getting the libraries up and running through the terminal—perhaps it is just easier on a Mac.

So here are the steps for installing the libraries:

1. Down load the latest version of the UCB STk from a link located at the top of the UCB Mac OS X install page. I am using STk-ucb1.3.6 in this tutorial.
2. Now double click on the downloaded dmg file and it will mount to the desktop, opening the UCB Scheme installation window. Open up an OS X Finder window where your “Applications” folder is accessible, and simply drag the “STk” folder to your “Applications” folder:
   
3. Now let’s test and see if it works. Open the Terminal application and enter the following command:

   /Applications/STk/bin/stk-simply

   If all is good, the Terminal will show the following:
   

4. Go ahead an run a few test functions. I did a basic Scheme expression and tested the UCB Scheme procedure “bf” (butfirst):
   
5. So the STk is working! Once you’re done playing around, use the “(exit)” command to close the STk.

A few notes, Cal Berkeley uses the UCB Simply STk (stk-simply) for the CS 3 and the CS 61 courses. There are other libraries in the STk folder for different purposes. For example, if you were to run the standard STk “/Applications/STk/bin/stk” then UCB procedures such as “bf” and “se” will not work. Throwing together scheme expressions is cool, but using Emacs for editing functions in external files takes it to another level and is essential for simulating the UCB lab environment.

Installing Emacs

A text based Emacs was already installed on my version of OS X. It is fairly easy to access from the Terminal application, but it lacks the benefits of a more visual application. For this part of the tutorial, I’ll do a quick demonstration of the text based Emacs, recommend more visual versions of Emacs (providing links), and show how to install a file that will make the visual version of Emacs behave very similar to the one on the UCB servers.

1. To open Emacs within the Terminal type and enter “emacs”; on my computer, I tried “emacs &” and “emacs&” in both the Terminal and X11, but neither open Emacs in a separate window. I won’t go into further details on this, for I prefer the visual applications in the later steps. Anyhow, if Emacs is installed on your computer then the “emacs” command will open the Emacs application as so:
   
   So let’s close that out and continue.
2. I found two very good Emacs applications. Carbon Emacs is recommended by UCB and seems to perform the most like UCB Emacs on the server, Carbon Emacs hompage. Aquamacs is an alternative that behaves a little different then UCB’s Emacs, but it includes the line cursor (similar to word processors) and tab view for files, Aquamacs homepage. Aquamacs is certainly worth looking more into—especially with the tab view option, but since Carbon Emacs works so similar to UCB’s Emacs out of the box, I will use Carbon Emacs for this tutorial. So download and install Carbon Emacs from their homepage.
3. Now we’ll setup Carbon Emacs to work as Emacs on the UCB Server, and this is by installing and editing a file titled “emacs.simply” from the UCB STk disk image to your home folder. This and the following two steps are very important for simulating the UCB Emacs environment; without editing the file, line returns will not automatically indent (in both Carbon Emacs and Aquamax) and the “command s” function will not split the window and automatically run the STk (Carbon Emacs only, there are other ways to run the STk in Aquamax). So, with that said, browse to the “Extras” folder located on the UCB Scheme disk image and locate the “emacs.simply” folder. Drag it to your home folder:
   
4. Open the emacs.simply file in TextEdit and locate the following line:

   (concat stkhome “/share/emacs/lisp”)))

   
   Change it to:

   (concat stkhome “/share/emacs”)))

   Save and close the file.

5. Now let’s rename the “simply.emacs” file to “.emacs”. OS X will not let you edit this file in the finder, but it can be easily done in the Terminal application. So open a new Terminal window and enter the following command:

   mv emacs.simply .emacs

   Check your home folder with the Finder, and the “simply.emacs” will no longer be there. That’s because “simply.emacs” is now “.emacs”; all files staring with a period will not show in the Finder unless you force it to do so.

6. Now we’ll test Carbon Emacs by creating file with UCB STk library procedures. When opening Carbon Emacs you’ll be prompted with a screen very similar to that of Emacs on the UCB Server; however, this version of Emacs will run much faster and has more standard OS X options for editing…such as undo!
   
7. Select “Insert File” from the “File” menu, and save the file as “pigl.scm”. Now type the following code into the editor:

   (define (pigl wd)
     (if (pl-done? wd)
         (word wd 'ay)
         (pigl (word (bf wd) (first wd)))))
   
   (define (pl-done? wd)
     (vowel? (first wd)))
   
   (define (vowel? letter)
     (member? letter '(a e i o u)))
   

   Notice how each line return automatically inserts tab formatting:
   

8. Save your file and use the “command s” shortcut; the window will split and the UCB STk will start running:
   
9. Load “pigl.scm” by entering the following line:

   (load “pigl.scm”)

   Test the pigl function/procedure by entering:

   (pigl ‘apple)

   And the output should be appleay, like so:
   

A few extra notes, the shortcut commands are a bit strange in Carbon Emacs. For example I was having trouble copying and pasting code from a text file to the Carbon Emacs editor; however, I was able to select and drag the text into the editor. The cut and paste commands in Aquamax work as normal, yet another reason to consider a switch. Other than that, I hope this tutorial clears up any confusion on getting a UCB Scheme and Emacs environment working on OS X.

Resources

UCB Scheme Mac OS X Binary Distribution – includes details on and a download for the libraries and important emac files for creating the UCB environment.

UCB CS 61A – website for info on UCB Computer Science introductory course, links to current semester.

Simply Scheme: Introducing Computer Science – Brian Harvey’s and Mathew Wright’s book that introduces computer science with UCB Scheme.

UCB 3 – website for info on UCB Scheme introductory course, links to current semester.

Carbon Emacs – OS X Emacs application that works very similar to UCB’s setup, recommended by UCB.

Aquamacs – very versatile and functional OS X Emacs application, comparable too if not better than Carbon Emacs.