Using the SML/NJ System

This page covers some basic questions on how to use the SML/NJ system.

How do I start SML?

Under Unix, you should make sure that the bin directory containing the sml command is in your path (defined by the PATH shell variable). If SMLHOME is defined to be the directory where SML/NJ was installed, then the sml command would be $SMLHOME/bin/sml. Another common place where the sml command might be installed is the directory /usr/local/bin. You can invoke sml by giving a full file name

  /usr/local/bin/sml

or, if the sml command is in a directory in your path, just type:

  sml

Under Windows, you can run SML/NJ by double clicking on the SML icon. Or ...

How do I quit SML?

Typing the EOF character at the interactive top level will quit sml. The EOF key is typically ctrl-D under Unix and ctrl-Z under Windows, where you'll need to press the return/enter key to make it take effect. Another method is to call the function OS.Process.exit:

  OS.Process.exit(OS.Process.success);

The two status values definied in OS.Process are success and failure. See the OS.Process documentation. The OS.Process.exit function is the proper means of quiting sml from within a program.

How do I load a program from a file?

The function

  use: string -> unit

is defined at top level and will load a file containing SML source code if applied to a string containing the name of the file (i.e. a file path name in the syntax of the host operating system). For instance

  use "../lib/sort.sml";

would cause the contents of the file "../lib/sort.sml" (assuming Unix file name syntax) to be loaded into the top-level interactive system as though it had been typed or pasted into the top-level interactive loop.

The function name use is a top-level synonym for the function Compiler.Interact.useFile.

The use function is convenient and adaquate for casual use, but it is not the recommended way to load an entire multifile program. For serious program development, it is much better to use the facilities of the compilation manager, CM.

How do I load libraries?

It depends on what you mean by "load". A brute force method would be to determine the pathname of the source code for the library and load the source code with the "use" command, but this is not recommended. A much better technique is to use CM, the built-in Compilation Manager.

If you want to use a library as part of a CM-managed program, then you simply list the library's description file in your own project's description file.

If you want to be able to access the bindings that the library exports at the interactive prompt, then you must issue the command:

  CM.make' ("<library-description-file>", false);

or, if you are using the latest "working" version of SML/NJ (110.9 or later):

  CM.make' { group = "<library-description-file>",
             force_relink = false };

Of course, you must replace the placeholder <library-description-file> with the pathname of the library's description file (note that CM uses the shell environment variable CM_PATH when looking for description files). If the pathname of the library happens to be simply "sources.cm", then you don't need to specify it at all. In that case simply say

  CM.make ();

CM also provides an autoloading feature, which causes selected library modules to be loaded automatically when they are mentioned in the interactive system. By default, the Util and Unix sections of the SML/NJ Library are registered for autoloading when the SML/NJ system is built. This means that if you refer to any of these library modules in code entered into the interactive system (directly or via the function use), they will be loaded automatically by CM. Which libraries are initially registered for autoloading is determined by variables set in the config/targets file, but users can register their own libraries for autoloading using the CM.autoload' function.

See the CM manual for further information.

How do I determine the current directory of the SML process?

The function OS.FileSys.getDir returns the current directory of the interactive loop or of an SML program that calls it.

How do I change the current directory of the SML process?

The function OS.FileSys.chDir sets the current directory of the interactive loop or of an SML program that calls it.

How do I save an SML image?

To save a heap-image of the SML/NJ interactive system, use the function

  exportML: string -> bool

which is defined in the SMLofNJ structure. A call such as

  exportML "image"

causes a heap image to be saved as image.arch-opsys where arch-opsys designates the architecture and operating system (e.g. image.sparc-solaris). The original call of exportML returns false.

How do I run a saved SML image?

Having created a heap image file, say image.arch-opsys with the exportML function, you can run the image, resuming the interactive loop from the point where exportML was called by executing

  sml @SMLload=image.arch-opsys

(where arch-opsys will be a particular architecture, operating system combination like "sparc-solaris"), or just

  sml @SMLload=image

since sml can figure out the right arch-opsys suffix. Execution will resume at the point where exportML returned, with the return value being true to indicate that we are in the resumed image.

How do I create a stand-alone SML application?

To create a stand-alone application, use the function

  exportFn: (string * ((string * string list) -> OS.Process.status)) -> unit

which is defined in the SMLofNJ structure. This function also produces a heap image file that must be passed as an @SMLload parameter to sml to be run. If you want to create a simple executable image, see the following question.

How do I create an executable image for an SML/NJ application?

It is possible to combine a heap image with the SML/NJ runtime to create a normal executable file by using Lorenz Huelsbergen's heap2exec utility.