Setting up Emacs for use with PLT Scheme on Windows or Mac OS X*

Emacs is the preferred Scheme source code editor for many experienced PLT Scheme developers; however, it is not easy for an Emacs neophyte to get an Emacs environment set up and configured properly for Scheme development. The problem is compounded if the development platform is Microsoft Windows since Unix (and variants) is the more common platform used by experienced Scheme developers. In order to help a Scheme beginner set up an Emacs Scheme development environment on a Microsoft Windows PC, this page will lay out step-by-step instructions for installing all the necessary components. It will also cover how these instructions can be adapted for use with Mac OS X.

By exactly following the installation instructions, the user will wind up with an Emacs setup that:

• Allows the user to use PLT Scheme (specifically, MzScheme) with Emacs with a number of Scheme-specific customizations.
• Configures Emacs so that it has keystroke bindings more similar to what a Windows user is accustomed to.
• Configures Emacs with a number of custom configuration settings that are commonly used.

Contents

The following steps will be covered:

1. Installing Emacs
2. Installing additional Emacs utilities
3. Installing on-line documentation (optional)
4. Installing PLT Scheme
5. Configuration steps
6. Testing the setup

There is also a short appendix describing the sample .emacs file and brief Mac OS X setup instructions:
   A.    Sample .emacs file
   B.    Mac OS X Setup Instructions

For each installation step, an installation directory is suggested. It is recommended that you install in the suggested directory since, if you use the suggested directory names, the provided Emacs start-up file (.emacs) will work "out-of-the-box". Please note the following:

• If you use alternative directory names, you will need to modify the .emacs file (instructions under "Configuration steps" below on where changes need to be made).
• The instructions assume you are using Winzip; however, you can use any alternative utility.
• When you unpack .gz files with Winzip, it will ask you "Should WinZip decompress it to a temporary folder and open it?" - click on "No". When you unzip any files, you should ensure that "All files" radio button is selected and the "Use folder names" check box is ticked.
• There are instructions for downloading a number of optional Emacs packages; however, it is not necessary to do so. Step #3 is required if you want local access to Scheme documentation. If you don't want/need the documentation, this step can be skipped or done at a later date.

1. Installing Emacs

• From a command line, create the following directories (used later): 

  md c:\home\
  md c:\home\site\
  md c:\home\info\
  md c:\bin\     

• Download the precompiled Emacs binaries for Windows from http://ftp.gnu.org/gnu/windows/emacs/emacs-21.3-fullbin-i386.tar.gz and use Winzip to unpack the files into the c:\bin directory. The Emacs directory should be renamed: c:\bin\emacs instead of c:\bin\emacs-21.3
  • Note: The GNU website was "hacked" back in 2003 and binaries were removed from the website by the maintainers as they weren't sure whether any viruses might have been attached to them. If the Windows Emacs binary still isn't available at the above location, you can download a pre-built CVS version of Emacs for Windows from http://www.crasseux.com/emacs/
• Using Run on the Windows Start menu, enter "c:\bin\emacs\bin\runemacs.exe" to verify that the program works. On the Help menu, there is an Emacs on-line tutorial. If you are unfamiliar with Emacs, you should (at least) complete this tutorial before proceeding any further. The remainder of these instructions will assume that you have at least basic familiarity with the use of Emacs.
• Download the sample .emacs startup file from here and place it in the c:\home directory. Note: The .emacs file is actually named "_emacs" since my ISP won't allow the upload of files with a leading "." in the name. This is OK (you don't have to rename the file) as Windows versions of Emacs accept a .emacs startup file that has either a name of ".emacs" or "_emacs".

2. Installing additional Emacs utilities

• Download Quack from http://www.neilvandyke.org/quack/quack.el and put it into the c:\home\site directory.
• Download my MzScheme startup file from here and place it in the c:\home directory.
• OPTIONAL: If you want Emacs to emulate the Windows-style buffer switching (e.g. - C-TAB to move from buffer to buffer), download the cua-emul.el utility from http://www.ph.ed.ac.uk/~p0198183/cua-emul.el and put it into the c:\home\site directory. If you want to use the Emacs defaults for buffer switching, don't download the cua-emul.el utility.
• OPTIONAL: The standard code colorization that is done by Emacs is not to everyone's taste. If you want to use my custom colorization scheme (included in the sample .emacs file) or use one of the standard ones that are included in this optional package (after installation, just press "M-x color-theme-select" to get a listing that you can select from), then download color-theme.el from http://www.emacswiki.org/elisp/color-theme.el.gz and and use Winzip to unpack the files into the c:\home\site directory.
• OPTIONAL: The Emacs Code Browser (ECB) is a useful utility for browsing code. However, installation is a bit involved and you might want to defer installation until you are more familiar with using Scheme with Emacs and decide whether it might be useful for your style of development. The sample .emacs file includes setup code for ECB if you do decide to install it. Follow the installation instructions on the ECB site and make certain that the installation directories are all in the C:\home\site\ directory and that they are named ecb, eieio, semantic and speedbar.

3. Installing on-line documentation (optional)

• OPTIONAL: Download the info version of the R5RS documentation from http://swissnet.ai.mit.edu/ftpdir/scm/r5rs.info.tar.gz and use Winzip to unpack the file into the c:\home\info directory. Lastly, add the following line to the "dir" file in the c:\bin\emacs-21.3\info directory:

  * R5RS: (r5rs). Revised(5) Report on the Algorithmic Language Scheme.

4. Installing PLT Scheme

• Download latest version of PLT Scheme from http://download.plt-scheme.org/drscheme/ and install it into the c:\bin\plt directory. Although it is possible to just download the mzscheme component if you are short on disk space, it is preferable to download the entire DrScheme install as it contains many optional components that you will probably find you want in the future.

5. Configuration steps

• Setup environmental variables either in the autoexec.bat file (e.g. - Windows/98) or the Control Panel/System (e.g. - Windows/NT/2000/XP):

• HOME: Should be set to c:/home (Note: use "/" rather than "\". Note also that you should make certain that you don't have both a User and a System HOME variable set up when setting up the HOME environmental variable under Windows/NT/2000/XP. If you do, the User variable will override the System one. Delete one of the two (better to leave the system one if you want multiple login users to use your same emacs configuration) and make certain that it is set to the c:\home directory.).
• PATH: The c:\bin\emacs\bin directory path should be prepended to the existing PATH to ensure that the Emacs executable can be found (e.g. -- set path=c:\bin\emacs\bin;%path%).

• If the specified directory locations were used, no changes to the .emacs file should be necessary. If file locations were changed, the directory locations that are specified in the first section of the .emacs file (the "Site-Specific Variables" section) should be modified with the correct directory locations (Note: when specifying directory locations in the .emacs file, use "/" rather than "\" as the directory separator character).
• Reboot the PC after making the above changes and configuration settings.
• Start Emacs (either by using the Start menu's Gnu Emacs shortcut or by using Run on the Windows Start menu with the command "c:\bin\emacs\bin\runemacs.exe") and do the following:
  • Compile the Quack utility:
    • Double-click on the "site" directory to drill down into that directory.
    • Compile the quack.el file by pressing "B" when the cursor is on the file name in the dired window (answer "y" to the "Byte-Compile (y or n)" prompt).
  • If you installed the cua-emul.el utility:
    • Double-click on the "site" directory to drill down into that directory.
    • Compile the cua-emul.el file by pressing "B" when the cursor is on the file name in the dired window (answer "y" to the "Byte-Compile (y or n)" prompt).
  • If you installed the color-theme.el utility:
    • Double-click on the "site" directory to drill down into that directory.
    • Compile the color-theme.el file by pressing "B" when the cursor is on the file name in the dired window (answer "y" to the "Byte-Compile (y or n)" prompt).
• All configuration steps should now be complete - exit Emacs by pressing "C-x C-c" and pressing "y" when you get the "Do you really want to exit Emacs ? (y or n)" prompt in the minibuffer.

6. Testing the setup

• Start Emacs (either by using the Start menu's Gnu Emacs shortcut or by using Run on the Windows Start menu with the command "c:\bin\emacs\bin\runemacs.exe") and do the following:
  • Press "F5" to start up MzScheme. You should get the Scheme prompt in a new buffer titled "*scheme*".
  • Press "C-x C-f" and type in test.scm when prompted for a file name. A new empty buffer will be created.
  • If you installed the documentation, you can test that the online documentation works by typing "(let" in the test.scm buffer and pressing "F1" (for the R5RS info documentation). This should open an Emacs Info buffer with the documentation for that keyword.
  • Exit Emacs by pressing "C-x C-c" and pressing "y" when you get the "Do you really want to exit Emacs ? (y or n)" prompt in the minibuffer. Note: Emacs will complain about a running process if you haven't stopped Scheme first. If you go ahead and quit then Windows generates an error. In order to avoid this, you can stop Scheme first with (exit) in the *scheme* buffer

You should now have a working Windows/Emacs/Scheme setup.

A. Sample .emacs file

• Following is a brief explanation of each of the sections of the sample .emacs file:
  • Site-Specific Variables: Contains directory locations for the Scheme, documentation and Emacs-specific files.
  • Initial Code Load: Loads Emacs files that are needed later on.
  • System Customizations: Some standard customizations that make Emacs easier to use.
  • Programming - Scheme: Scheme-specific setup. The following Scheme-specific bindings have been added:
    • F5 - Starts MzScheme.
    • Macroexpansion:
      • C-c Enter - Selects the s-expression at the cursor location for macroexpansion.
      • C-c e - Fully expands the selected s-expression.
      • C-c o - Expands the selected s-expression once.
      • C-c * - Expands the selected s-expression repeatedly.
      • C-c h - Shows the s-expression that will be acted on.
    • F1 - Brings up the R5RS Info documentation for the symbol that the cursor is on (if the documentation was installed).
    • C-c x - Evaluates the current region or s-expression (works in Scheme or Info mode).
    • C-c ; - Inserts "balanced" comments around the current s-expression (a prefix argument moves the comment out).
    • C-c : - Removes "balanced" comment.
    • C-c t - Trace the function at the cursor location (a prefix argument un-traces the function).
    • C-c T - Trace all functions in the current namespace (a prefix argument un-traces all functions).
  • Programming -  Elisp: Emacs Lisp-specific setup.
  • Standard Key Overrides: Some convenience key setups. The following key bindings have been added:
    • mouse-2 - Brings up a menu of symbols when in a Scheme/Elisp source file.
    • F4 - Closes current buffer window.
    • F6 - Switches focus to another window (when multiple windows are in an Emacs frame).
    • F7 - Closes all windows except for the window that currently has focus.
    • C-F7 - If ECB was loaded, toggles between multiple ECB windows and just a single source window.
    • M-F7 - If ECB was loaded, toggles between different ECB window layouts.
    • F12 - Emacs shell
    • C-F12 - Default shell
    • M-F12 - Bash shell (if present on computer)
    • C-c f - Finds the Emacs Lisp function at the cursor location.
    • C-c F - Finds the file whose name is at the cursor location.
    • C-c j - Joins current line with previous line.
    • C-c s - Search forward using the symbol that is currently under the cursor.
    • C-c r - Search backward using the symbol that is currently under the cursor.
    • C-c / - Do a word completion (using hippie-expand).
    • C-c g - Goto a line (prompts for line#).
    • C-c a - Select the entire buffer contents.
  • MS Windows Customizations: These settings make Emacs feel more like a Windows application. For Windows machines, they add the following bindings:
    • In dired mode, when you press the "w" key when the cursor is on a file name, the file will be opened with the default application for that file type.
    • When cua-emul.el is installed:
      • M-F4 - Close frame (closes Emacs if only one Emacs frame is open).
      • C-F4 - Close the current buffer.
      • C-TAB - Switch to next buffer.
      • C-S-TAB - Switch to previous buffer.
  • Mac OS X Customizations: Mac OS X specific customizations:
    • Keypad DEL - Deletes character under cursor.
    • C-kp-HOME - Goes to beginning of buffer.
    • C-kp-END - Goes to end of buffer.
  • Start Directory: After Emacs starts up, the start directory will be the HOME directory.
  • Customizations: Some customizations that can be overridden using the "Customize Emacs" menu option (on the Options menu).
    • Use CUA key bindings:
      • C-c - Standard Windows copy.
      • C-x - Standard Windows cut.
      • C-v - Standard Windows paste.
      • C-z - Standard Windows undo.
    • Use Greek lambda characters to represent "lambda".
    • Disable tool bar.
    • Some colorization customizations for Quack.

B. Mac OS X Setup Instructions

• This section lists the things that are different from the above Windows instructions. At this stage, support for Mac OS X on this page is very limited since I do not use Mac OS X on a regular basis. This section needs a lot of work - I would appreciate any feedback and/or suggestions to improve the Mac OS X instructions.
• There are multiple different versions of Emacs (some Aqua-ized, some not) for the Mac and there will eventually be an official FSF Emacs that supports the Aqua GUI. I used David Caldwell's Carbon build since the Mac I tested on had OS X version 10.2. Other Emacs builds on other versions of Mac OS X may or may not have problems using my .emacs file.
• All of the places in the above Windows instructions where "c:/home" is mentioned, you should substitute the path to your own home directory (referenced as "~/" in the remainder of these instructions). The .emacs file is setup in such a way that it is not necessary to set any environmental variables manually.
• The optional cua-emul.el utility caused some issues under Mac OS X; therefore, the .emacs file ignores them if you're not on Windows. I have not tested the optional ECB utility on Mac OS X but it should work with the settings that are in the .emacs file so long as all the components are installed in the directories that were specified under the Windows instructions. The optional color-theme.el utility works fine.
• The .emacs file that is supplied will work unchanged with either a Windows installation or a Mac OS X installation. For a Mac install, the assumed directory locations are listed below.
• PLT Scheme should be installed in the "~/bin/plt" directory.