Emacs and SML/NJ for CSE 341

Ben Wood, September 2011, adapted from instructions by Dan Grossman and Hal Perkins

For roughly the first half of 341, we will work with the Standard ML programming language, using the SML/NJ (Standard ML of New Jersey) compiler. You will need both SML/NJ and a text editor on whatever computer you use to do assignments. Any editor that can handle plain text will work, but you are strongly encouraged to use Emacs, for its SML Mode, which provides good syntax highlighting, indentation, and integration with the SML environment. Learning Emacs will probably serve you well in future CSE courses.

Both Emacs and SML/NJ are installed on all department Windows and Linux lab machines, but you will need to install them on your own machine if you want to use it for 341 assignments. You will need to set up SML Mode for Emacs whether you work on your own machine or in the lab.

This document describes how to use Emacs, SML/NJ, and SML Mode, as well as how to install and configure them properly on your own computer. These instructions should work for recent versions of Windows, Mac OS X, and Linux. If you are on a lab machine, start with the Emacs basics. If you are using a lab Windows machine, also skip SML/NJ installation.

Contents

1. Preamble: Extra Windows tools
2. Install Emacs
3. Emacs basics
4. Install SML/NJ
5. Install SML Mode in Emacs
6. Use the SML/NJ REPL (Read-Eval-Print Loop) in Emacs

Preamble: Extra Windows tools

This section is only for Windows users. Windows does not ship with support for some of the archive file formats (TAR, GZIP) in which Emacs and SML Mode are distributed. To be able to open these files and install their contents, download and install the free archive manager 7-Zip. The 32-bit installer should work with any Windows 7 system. Download and run this installer to install 7-Zip.

Install Emacs

Skip this if you are using a lab machine.

Personal Linux

If Emacs is not already installed, use your package manager to install it. (e.g., on Ubuntu and other Debian derivatives: sudo apt-get install emacs, on Fedora: sudo yum install emacs.)

Personal Windows

Download a ZIP archive of the most recent full version, currently Emacs 23.3. (More information and other versions of Emacs are available at the GNU Emacs website.)

Unpack the downloaded ZIP archive file (emacs-23.3-bin-i386.zip) by right-clicking it and choosing 7-Zip > Extract Here. This should give you a folder called emacs-23.3, which you can place anywhere you would like.

Once you have moved the emacs-23.3 folder to where you want it, look inside to find bin\addpm.exe (the .exe extension might not be visible in the folder window depending on how you have Windows configured). Double click on this file to run it one time and it should add a Gnu-Emacs folder to your Start menu and do some other setup operations. Open the Start menu and select Gnu-Emacs > Emacs to launch emacs.

Personal Mac OS X

Download Emacs as a Mac OS X application here. Open the disk image file (.dmg) and drag the Emacs application to your Applications folder. If you prefer another version of Emacs (e.g., the old school one on the command line or AquaMacs), feel free to use it.

Emacs basics

Driving Emacs is a little different than driving any other editor; it can take some getting used to, especially the keyboard shortcuts. Fortunately, the GUI versions of Emacs you will use on Linux, Windows, or Mac OS X all have some buttons and menus to help you adjust if that's your style. The following is a quick primer on Emacs terminology and keyboard commands.

Beyond the basics described here, the Emacs reference card (pdf) is a good reference. For more info, check out the Emacs Reference Manual or the Emacs Wiki.

• The cursor is a rectangular block and is referred to as the point.
• The mode line displays information about the buffer displayed in the current window. A buffer is a logical "thing" that you are working on. When you open a file, it will be loaded into a buffer, typically with the same name as the file.
• Every buffer is edited in a mode. The most basic mode is Fundamental, which provides only the most basic Emacs editing features. There are modes for many different languages.
• There are many "special" buffers that do not correspond to loaded files. The one above is called *scratch*. This buffer runs in Lisp Interaction mode, which means that you can interactively type and evaluate expressions in the Lisp programming language.

Emacs uses many key combinations involving the Control and Meta keys. Such key combinations are denoted C-x (Control-x (lowercase)) or M-x (Meta-x). On keyboards that don't have Meta (just about all keyboards today), try Alt on PC keyboards or the ⌘ or Option keys on a Mac keyboard. (Emacs might complain about "Super" if you get the wrong one. If you or Emacs gets confused about what you're trying to type, use C-g to cancel your current command and start fresh.) If none of these work, use ESC, but when trying to type "M-x", for example, type ESC then type "x". (This is only if using ESC as Meta. The other Meta "substitutes" work as usual: hold while pressing the second key.)

A sequence of key presses is written like C-a C-b M-x, which would mean do the three actions in sequence.

The most important keys in Emacs:

• C-x C-c: Quit Emacs
• C-g: Cancel the current action
• C-x C-f: Open a file (even if it doesn't exist yet)
• C-x C-s: Save a file
• C-x C-w: Write a file (probably more familiar to you as Save as...)

Cut, copy, paste:

• Highlight text with the mouse or by hitting C-space to set a mark and then moving the cursor to highlight a region.
• C-w: Cut a highlighted region
• M-w: Copy a highlighted region
• C-k: Cut (kill) the rest of the line to the right of the cursor
• C-y: Paste (yank)

Some other useful keys:

• C-x 2: Split the window into 2 buffers, one above the other. (Use the mouse or C-x o to switch between them.
• C-x 0: Undo window-splitting so there is only 1 buffer.
• C-x b: Switch to another buffer by entering its name.
• C-x C-b: See a list of all current buffers.

Getting help within Emacs: In addition to the help button on the right...

• C-h: Help. Hitting this will display a short message in the minibuffer: C-h (Type ? for further options).
• C-h t: Built-in interactive tutorial. Some people don't like this tutorial, but some people find it helpful.
• C-h b: Key bindings. This lists all key bindings that are valid for the current mode. Note that key bindings change from mode to mode!
• C-h a: Command apropos. After hitting C-h a you can type a symbol and a window will appear that lists all symbols and functions that match that phrase.

More advanced Emacs hacks (optional)

• Change the default directory for C-x C-f: When you first start up emacs and use C-x C-f to open a (new or existing) file, it will start you by default at either "~/" on Linux or Mac OS X (your home directory/folder) or another prechosen folder in Windows. To change that default location to whatever location you want, add this line to your "~/.emacs" file (a configuration file emacs reads when it starts -- create it if it doesn't exist), replacing "whatever" with the path of the folder you'd like to be the default, then restart emacs:

    (setq default-directory "whatever")

  Don't forget to escape (double) your backslashes in paths on Windows, as backslash is a special character in the emacs configuration language just like it is for strings in Java.
• Change the colors of your syntax highlighting: see the color-theme package. Some .emacs hacking required.
• General customization interface: Open the Options menu and choose the first item under Customize Emacs. This will let you customize Emacs through a sort-of-GUI interface. It saves all of your settings in a second file and adds a line in your ~/.emacs file that loads the settings in that file.

Install SML/NJ

Skip this if you are using a lab Windows machine.

Lab Linux

Run this only once. It will set up SML/NJ in your account for all physical lab Linux machines. (If you use the department's Linux VM image on your machine, SML/NJ is not preinstalled. You will need to follow the installation instructions for Personal Linux below.)

Open a terminal (Click on Activities in the upper left of the screen, then Applications and scroll to find it. Or search.) and enter the following command:

  /cse/courses/cse341/11au/smlnj-setup.sh

Hit enter. It should print the following self-explanatory message:

  SML/NJ is ready to go!

Close this terminal before trying any other commands.

NOTE: If you're used to using ssh to work remotely on attu, you must ssh to attu32 instead to be able to use SML/NJ. SML/NJ will not work on regular attu, but will work on attu32. If you didn't understand that, don't worry, you can ignore it!

Personal Linux

If your package manager has a package for SML/NJ, install it. Otherwise, follow the "Unix" instructions here.

Personal Windows

Download and run the smlnj.msi installer available here. This will add an item for SML of New Jersey to your Start menu and add a command sml that you can use at the command line.

Personal Mac OS X

Download the installer available here. (Unless your Mac was born before about 2006, you probably want the Intel (x86) version.) Open the disk image file (.dmg) and run the installer.

Once the installation is complete, use Emacs or another text editor to edit the file ".bash_profile" in your home folder. (In Emacs you can do this via: "C-x C-f   ~/.bash_profile".) If it does not already exist, create it. Add the following line to make sure SML is visible on the command line (if you chose a custom install location, change "/usr/local/smlnj-110.73" to whatever that location is):

  export PATH="$PATH:/usr/local/smlnj-110.73/bin"

This tells your shell (the program that you interact with in the terminal) to add the SML/NJ programs to the paths it searches for command you enter. (If you are not using the bash shell, which Mac OS X has used by default since 10.3, the syntax will be different.)

All Systems: Check your SML Installation

Open a terminal (Windows: Start > All Programs > Accessories > Command Prompt, Mac OS X: Applications/Utilities/Terminal.app), type "sml", and hit enter/return. (Or on Windows, use the Start menu item for SML/NJ if you prefer.) SML/NJ should print a short banner followed by a prompt:

  Standard ML of New Jersey v110.73 [built: Sun May 15 21:34:53 2011]
  -

Make sure everything is working by typing a very simple SML program at the prompt:

  1 + 1;

Hit enter/return. In response, the SML interpreter should print something like this:

  val it = 2 : int
  -

To exit the interpreter, type Control-D on Linux or Mac or Control-Z on Windows.

Install SML Mode in Emacs

Skip this if you are using a lab Linux machine, but make sure you did the setup described in the Install SML/NJ: Lab Linux section.

SML Mode is an extra extension to Emacs that is not Emacs itself or SML/NJ itself. It displays SML code nicely with syntax coloring and clean indentation, and provides a way to run SML from within Emacs. Go to http://www.iro.umontreal.ca/~monnier/elisp/ and download the latest version. Unpack it:

• Windows: use 7-Zip again. Right-click the .tar.gz file and choose 7-Zip > Extract Here.
• Mac OS X: double-click the .tar.gz file.
• Linux (Ubuntu, Fedora/lab machines, likely others): when downloading, choose Open with [Archive Manager] if given the option. Otherwise, save the file and double-click it, which should open it in Archive Manager. Drag the sml-mode-4.1 folder to the Desktop or wherever you want to store it.
• Linux, general: save the file and, in a terminal, cd into the directory where sml-mode.tar.gz was downloaded and run tar xfz sml-mode.tar.gz.

You should get a folder named sml-mode-4.1 (the current version). You can place this folder anywhere you like, although if you are running in the CSE labs you should put it somewhere in your user file directories (Z drive on Windows); not on the local disk of a particular machine.

To get sml mode to work with emacs, you need to create a .emacs file in your "home" directory/folder that emacs searches when it starts up. The easiest way to get this right is to use emacs itself to create the .emacs file. Run emacs and enter the command C-x C-f   ~/.emacs. Emacs expands the "~" to the path where it actually does look for its configuration file; this works correctly on Windows, OS X, and Linux.

Add the following two lines:

  (setq load-path (cons "path/to/where/you/stored/sml-mode-4.1" load-path))
  (load "sml-mode-startup")

Replace "path/to/where/you/stored" with the appropriate path. To get the path of a folder:

• In Windows, hold down the Shift key as you right-click the folder, and choose Copy As Path.
• In Mac OS X, select the folder in the Finder and choose File > Get Info (⌘-I). Copy the Where: field.

On Windows machines, the path can look like "Z:\\look\\here", but each backslash (\) needs to be doubled (\\) because backslash by itself is a special meta-character in emacs settings files and a pair \\ is needed to represent each backslash in the path.

If you're on Linux, depending on how you launch emacs, you might need to follow the next Mac-oriented step. You only do this if SML mode seems to work, but you can't get the SML REPL to run in emacs, and you'll need to replace the path given here with wherever your smlnj install lives.

If you're on a Mac, you'll need to tell Emacs a little more about your SML install. Add the following to the .emacs file:

  (setenv "PATH" (concat "/usr/local/smlnj-110.73/bin:" (getenv "PATH")))
  (setq exec-path (cons "/usr/local/smlnj-110.73/bin"  exec-path))

For everyone: To verify that sml mode is properly installed, exit emacs then restart it so it will read the new .emacs file. Then edit an existing or new sml file (try C-x C-f test.sml to create a new file if nothing else is handy). You should see the mode display at the bottom of the emacs window change from Fundamental (or whatever it was) to SML. If you enter a line of code like val n = 1; you should see colors highlighting the keywords and variable names. When you're editing code, whenever you hit the TAB key, emacs will try to reindent the current line appropriately.

If you're in SML Mode but your SML code does not have syntax coloring, add this line to your ~/.emacs file:

  (global-font-lock-mode t)

(There are much more elaborate installation instructions in the documentation included in the sml-mode folder, but these are aimed at system administrators who might want to install sml mode for an entire site instead of a single user. Please ignore these - what's given here is all you need.)

Use the SML/NJ REPL (Read-Eval-Print Loop) in Emacs

Alright, we're done installing! This section will show you how to run SML programs from within Emacs. It assumes you already have an SML file or can write your own SML program in a new one.

1. Start emacs from a terminal in the directory where you have (or will have) your .sml files. (Justification: That way, when you type use "foo.sml" in the REPL, it will look for "foo.sml" in the directory you want.)

2. Use SML-mode only for files ending in .sml. See other notes for how to modify your .emacs file appropriately. (Emacs is pretty smart about selecting what mode to use based on the file extension.)

   • Use the tab key to indent your code. Style matters!

3. To create the *sml* buffer (which holds the REPL), type C-c C-s (and then return) in the buffer with the .sml file. (Note: This will not work in the scratch buffer that emacs starts in.)

4. To end and restart a REPL session, type C-d (to end it) and C-c C-s (and then return) (to restart it). You must type C-d while in the *sml* buffer; you can type C-c C-s from the *sml* buffer or a buffer with a .sml file.

5. By ending and restarting a session, the new session has an empty environment. Your earlier interactions are still in the *sml* buffer, so you can save them, cut-paste them, etc., but they have no effect on the evaluation in the restarted REPL session.

6. Evaluation can go into an infinite loop.

   • This has likely occurred if you are not getting the "- -" prompt back and nothing appears to be happening.
   • C-c C-c will interrupt evaluation and get you your prompt back.

7. If you forget to end your binding with a ";" character, the REPL will print an "=" character on the next line, which is just its way of saying "you're not done -- continue your binding", so type a ";" and hit return. This is not an infinite loop (nothing is being evaluated; the REPL is waiting for you) so C-c C-c doesn't do anything.

8. If the printed result looks "pretty good", but part of what you expected to see has been replaced by a "#" or "...", don't worry. The REPL has a limit on how many characters it prints, which is good since you might make a large value, such as a list with tens of thousands of elements. You can adjust the limit if you want.

Advice you'll wish you followed!

1. In each REPL session, follow this pattern:

   • first type use "foo.sml"; for any sml files you want to use
   • then use the REPL manually as long as you wish
   • but do not use use to load (or reload) any more files
   • when tempted to violate the previous point, end and restart your REPL session

   Why: use "foo.sml" has a very simple semantics: it adds the bindings in the file to the environment in order. These may or may not shadow bindings from the last time you typed use "foo.sml", depending on how "foo.sml" changed. This confuses even expert programmers until they train themselves to follow the pattern above.

2. If you find yourself typing the same non-trivial things over and over again in the REPL, stop wasting your time.

   • move the repeated parts to a second file, e.g., test.sml
   • then (see part a), when you restart your session, begin with use "foo.sml"; use "test.sml";
   • in fact, there's an even faster way!
     • begin test.sml with the expression use "foo.sml";
     • then begin your session with use "test.sml";

   Note: Do not put use "foo.sml" in test.sml and begin your session with use "foo.sml"; use "test.sml". That will evaluate the bindings in foo.sml twice, which is confusing.

3. If you develop some emotional attachment to the transcript of your *sml* buffer, you can save it to a file just like any other buffer. But after you do, it's not an *sml* buffer anymore, so you will have to create a new *sml* buffer (see (3) above).

Updates

10/2/2011 clarified advanced emacs hacks section - BPW
9/30/2011 miscellaneous tweaks, added extra PATH setup for Mac OS X, added advanced emacs config section - BPW
9/26/2011 reorganize and add emacs/sml/repl primer -BPW
3/31/2011 add information about \\ in .emacs files. HP