heap2exec is a simple utility for building stand-alone executables from SML/NJ heap images, typically produced by SMLofNJ.exportFn or SMLofNJ.exportML.

heap2exec wraps the binary smlnj runtime image and an smlnj heap image into one executable image.

The heap2exec program can be downloaded from the ftp directory:

The source code for heap2exec is in the file heap2exec.tar.gz, which needs to be unpacked using gunzip and tar.


First, a special version of the runtime is required to support stand-alone executables; that is, the runtime must be able to detect and extract piggy-backed heap images. To do this, in the src/runtime/objs directory, make a copy of the makefile for the processor-OS for which a standalone executable is desired. For example:
	cp mk.x86-linux mk.x86-linux-standalone
Edit the new copy (i.e., mk.x86-linux-standalone) and place -DHACKED_STANDALONE as the last entry on the new makefile's DEFS list. Also, change the name of the runtime to run.<arch>-<os>-standalone on the makefile's RUNTIME entry.

Next the heap2exec utility needs to be built. Change to the heap2exec directory. Issue a 'make' in the heap2exec directory to produce heap2exec.

Given a runtime built with HACKED_STANDALONE defined (as described above) and an exported heap image (i.e., your program), invoke heap2exec as

	heap2exec the-runtime the-heap the-executable
where 'the-runtime' is the standalone smlnj runtime (run.<arch>-<os>-standalone) to put into the stand-alone executable and 'the-heap' is the smlnj heap to put in the stand-alone 'the-executable'.

Relative Paths

Relative paths are somewhat problematic with heap2exec since the resulting executable uses its own name (argv[0]) as the name of the image to load. If you want to place your executable in /usr/bin/ and invoke it as myprog, for example, name it myprog.heap2exec and place it in /usr/bin/. Then create a shell script /usr/bin/myprog with the content:

	#! /bin/ksh
	/usr/bin/myprog.heap2exec $*
Now if /usr/bin/ is in your path (and you remembered to 'chmod +x myprog'), you should be able to invoke the executable from anywhere.

(Note: A new version of the runtime that will be able to generate stand-alone executables directly is planned for the next release.)

Author: Lorenz Huelsbergen

Dave MacQueen
Last modified: Thu Jun 24 18:28:40 EDT 1999