Install Sml

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

1. Install Sml Movie
2. Install Smallpdf Chrome Extension

For roughly the first half of 341, we will work with the Standard ML programminglanguage, using the SML/NJ (Standard ML of New Jersey) compiler. You will needboth 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 stronglyencouraged to use Emacs, for its SML Mode, which provides good syntaxhighlighting, indentation, and integration with the SML environment. LearningEmacs will probably serve you well in future CSE courses.

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

Go to your Satisfactory install folder (Usually C:/Program Files/Epic Games/SatisfactoryEarlyAccess or SatisfactoryExperimental), go to FactoryGame, Binaries, then Win64. Place your xinput13.dll file there. Run FactoryGame-Win64-Shipping.exe. If a console window appeared, SML is good to go! SML/NJ 110 provides a native code compiler that can be used interactively and can also build stand-alone applications, along with a programming environment made up of various tools (CM, ML-Lex, ML-Yacc, CML, eXene, etc.), and a collection of libraries (smlnj-lib). Satisfactory mods, tools, guides and forums. An extension to the FICSIT industries.

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

Contents

Preamble: Extra Windows tools

This section is only for Windows users. Windows does not ship with support forsome of the archive file formats (TAR, GZIP) in which Emacs and SML Mode aredistributed. To be able to open these files and install their contents,download and install the free archive manager 7-Zip.The 32-bit installershould work with any Windows 7 system. Download and run this installer toinstall 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 Emacs23.3. (Moreinformation and other versions of Emacs are available at the GNU Emacswebsite.)

Unpack the downloaded ZIP archive file (emacs-23.3-bin-i386.zip) byright-clicking it and choosing 7-Zip > Extract Here. This should give you afolder 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 tofind binaddpm.exe (the .exe extension might not be visible in the folderwindow depending on how you have Windows configured). Double click on this fileto run it one time and it should add a Gnu-Emacs folder to your Start menuand 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 yourApplications folder. If you prefer another version of Emacs (e.g., the oldschool one on the command line or AquaMacs), feel freeto use it.

Emacs basics

Driving Emacs is a little different than driving any other editor; it can takesome getting used to, especially the keyboard shortcuts. Fortunately, the GUIversions of Emacs you will use on Linux, Windows, or Mac OS X all have somebuttons and menus to help you adjust if that's your style. The following is aquick 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 inthe current window. A buffer is a logical 'thing' that you are workingon. When you open a file, it will be loaded into a buffer, typically with thesame name as the file.
• Every buffer is edited in a mode. The most basic mode isFundamental, 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. Theone above is called *scratch*. This buffer runs in LispInteraction mode, which means that you can interactively type and evaluateexpressions in the Lisp programming language.

Emacs uses many key combinations involving the Control and Metakeys. Such key combinations are denoted C-x (Control-x (lowercase)) orM-x (Meta-x). On keyboards that don't have Meta (just about allkeyboards today), try Alt on PC keyboards or the ⌘ or Option keys ona 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 tocancel 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 isonly if using ESC as Meta. The other Meta 'substitutes' work as usual: holdwhile pressing the second key.)

A sequence of key presses is written like C-a C-b M-x, which would meando 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 andthen 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 theother. (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 inthe minibuffer: C-h (Type ? for furtheroptions).
• C-h t: Built-in interactive tutorial. Some people don'tlike this tutorial, but some people find it helpful.
• C-h b: Key bindings. This lists all key bindingsthat are valid for the current mode. Note that key bindingschange from mode to mode!
• C-h a: Command apropos. After hitting C-ha you can type a symbol and a window will appear that listsall symbols and functions that match that phrase.

More advanced Emacs hacks (optional)

If you'e curious, try some of these once you've finished the rest of the setup instructions. They are unnecessary for any of the work we'll do, but may be convenient.

• 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: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 Linuxmachines. (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 thescreen, then Applications and scroll to find it. Or search.) and enter thefollowing command:

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

Close this terminal before trying any other commands.

NOTE: If you're used to using ssh to work remotely on attu, you must sshto 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 canignore it!

Personal Linux

If your package manager has a package for SML/NJ, install it.Otherwise, follow the 'Unix' instructionshere.

Personal Windows

Download and run the smlnj.msi installer availablehere. This will add anitem for SML of New Jersey to your Start menu and add a command sml thatyou can use at the command line.

Personal Mac OS X

Download the installer availablehere. (Unless your Macwas born before about 2006, you probably want the Intel (x86) version.) Openthe disk image file (.dmg) and run the installer.

Once the installation is complete, use Emacs or another text editor to edit thefile '.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 thefollowing line to make sure SML is visible on the command line (if you chose acustom install location, change '/usr/local/smlnj-110.73' to whatever thatlocation is):

This tells your shell (the program that you interact with in the terminal) toadd the SML/NJ programs to the paths it searches for command you enter. (If youare not using the bash shell, which Mac OS X has used by default since 10.3, thesyntax 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 hitenter/return. (Or on Windows, use the Start menu item for SML/NJ if youprefer.) SML/NJ should print a short banner followed by a prompt:

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

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

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 didthe setup described in the Install SML/NJ: Lab Linuxsection.

SML Mode is an extra extension to Emacs that is not Emacs itself or SML/NJitself. It displays SML code nicely with syntax coloring and cleanindentation, and provides a way to run SML from within Emacs. Go to http://www.iro.umontreal.ca/~monnier/elisp/and download the latestversion. 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, chooseOpen with [Archive Manager] if given the option. Otherwise, save the fileand double-click it, which should open it in Archive Manager. Drag thesml-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 directorywhere 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 currentversion). You can place this folder anywhere you like, although if you arerunning in the CSE labs you should put it somewhere in your user filedirectories (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 wayto 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 '~' tothe path where it actually does look for its configuration file; this workscorrectly on Windows, OS X, and Linux.

Add the following two lines:

Replace 'path/to/where/you/stored' with the appropriate path. To get the pathof 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 andchoose File > Get Info (⌘-I). Copy the Where: field.

On Windows machines, the path can look like 'Z:lookhere', but eachbackslash () needs to be doubled () because backslash by itself is aspecial meta-character in emacs settings files and a pair is needed torepresent 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:

For everyone: To verify that sml mode is properly installed, exit emacs then restart it so itwill read the new .emacs file. Then edit an existing or new sml file (tryC-x C-f test.sml to create a new file if nothing else ishandy). You should see the mode display at the bottom of the emacs window changefrom Fundamental (or whatever it was) to SML. If you enter a line of code likeval n = 1; you should see colors highlighting the keywords andvariable names. When you're editing code, whenever you hit the TAB key, emacswill 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:

Install Sml Movie

(There are much more elaborate installation instructions in the documentationincluded in the sml-mode folder, but these are aimed at system administratorswho might want to install sml mode for an entire site instead of a singleuser. 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 SMLprograms from within Emacs. It assumes you already have an SML file or canwrite 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' inthe 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 tomodify your .emacs file appropriately. (Emacs is pretty smart aboutselecting 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 (andthen return) in the buffer with the .sml file. (Note: This will not work inthe 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 savethem, cut-paste them, etc., but they have no effect on the evaluation in therestarted REPL session.

6. Evaluation can go into an infinite loop.

   • This has likely occurred if you are not getting the '- -' promptback 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 willprint 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 iswaiting 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 tosee has been replaced by a '#' or '...', don't worry. The REPL has a limiton how many characters it prints, which is good since you might make a largevalue, such as a list with tens of thousands of elements. You can adjust thelimit 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 yourREPL session

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

2. If you find yourself typing the same non-trivial things over andover 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 sessionwith use 'foo.sml'; use 'test.sml'. That will evaluate the bindings infoo.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 youdo, it's not an *sml* buffer anymore, so you will have to create a new*sml* buffer (see (3) above).

Install Smallpdf Chrome Extension

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