World Images

A world image is a file that contains a complete Scheme system, perhaps additionally including user application code. Scheme provides two methods for saving and restoring world images. The first method writes a file containing all of the Scheme code in the world, which is called a band. The file `runtime.com' that is loaded by the microcode is just such a band. To make your own band, use the procedure disk-save.

procedure+: disk-save filename [identify]

Causes a band to be written to the file specified by filename. The optional argument identify controls what happens when that band is restored, as follows:

not specified

Start up in the top-level REPL, identifying the world in the normal way.

a string

Do the same thing except print that string instead of `Scheme' when restarting.

the constant #t

Restart exactly where you were when the call to disk-save was performed. This is especially useful for saving your state when an error has occurred and you are not in the top-level REPL.

the constant #f

Just like #t, except that the runtime system will not perform normal restart initializations; in particular, it will not load your init file.

To restore a saved band, give the -band option when starting Scheme. Alternatively, evaluate (disk-restore filename) from a running Scheme, which will destroy the current world, replacing it with the saved world. The argument to disk-restore may be omitted, in which case it defaults to the filename from which the current world was last restored.

Note: with the C back-end, disk-save is not very useful. The reason is that compiled procedures are compiled C code that has been dynamically linked in, and disk-save does not save any C procedures. If you need to build a band for a C back-end system, please contact us. Your system is a C back-end system if the following expression does not evaluate to #f:

(system-library-directory-pathname "shared")

Note: when restoring a saved band, the Scheme executable must be configured with a large enough constant space and heap to hold the band's contents. If you attempt to restore a band using the -band option, and the band is too large, Scheme will write an error message that tells you the appropriate command-line options needed to load that band. If you attempt restore a too-large band using disk-restore, Scheme will signal an error, but will not provide the configuration information. In general, the configuration that was used to save a band is sufficiently large to restore it.

Another method for saving the world is the dump-world procedure, which accepts the same arguments as disk-save and works in much the same way. However, rather than dumping a band, dump-world saves an executable image, which is started just like any other program. This has the advantage of being considerably faster to start on some systems, but the image file is typically much larger than the corresponding band. However, dump-world is only supported for a few operating systems, and is not built into the distributed executable files -- if you wish to use dump-world, you must build your own executable file from the source code. Note that dump-world is unlikely to work with this release as MIT Scheme now uses shared libraries.