1.1 Unix Installation

We will use as an example the installation for GNU/Linux. The installation for other unix systems is similar. There are several references to ARCH below; these refer to the computer architecture that Scheme is compiled for: either ‘i386’ ‘x86-64’, ‘aarch64’, or ‘svm1’.

MIT/GNU Scheme is distributed as a compressed ‘tar’ file. The tar file contains both source and binary files; the binary files are pre-compiled Scheme code for a particular computer architecture. The source files are C programs that need to be compiled.

Requirements

At a minimum, you will need a C compiler (e.g. ‘gcc’) and a ‘make’ program, and a “curses” library. For example, here are the packages that must be installed on some popular systems:

• Debian-like systems: gcc make m4 libncurses-dev
• CentOS-like systems: gcc make m4 ncurses-devel
• macOS systems: Command line developer tools ‘xcode-select --install’

Additionally, if you want support for X11 graphics, you’ll need:

• Debian-like systems: libx11-dev
• CentOS-like systems: libX11-devel
• macOS systems: XQuartz (from https://www.xquartz.org/)

Steps

In order to install the software, it’s necessary to configure and compile the C code, then to install the combined C and Scheme binaries, with the following steps.

1. Unpack the tar file, mit-scheme-VERSION-ARCH.tar.gz, into the directory mit-scheme-VERSION. For example,

   tar xzf mit-scheme-VERSION-i386.tar.gz
   

   will create a new directory mit-scheme-VERSION.

2. Move into the src subdirectory of the new directory:

   cd mit-scheme-VERSION/src
   

3. Configure the software:

   ./configure
   

   By default, the software will be installed in /usr/local, in the subdirectories bin and lib. If you want it installed somewhere else, for example /opt/mit-scheme, pass the --prefix option to the configure script, as in ./configure --prefix=/opt/mit-scheme.

   The configure script accepts all the normal arguments for such scripts, and additionally accepts some that are specific to MIT/GNU Scheme. To see all the possible arguments and their meanings, run the command ./configure --help. However, do not specify the following options, which are all preconfigured to the right values; doing so will probably cause the build to fail:

   --enable-native-code
   --enable-host-scheme-test
   --enable-cross-compiling
   --with-compiler-target
   --with-default-target
   --with-scheme-build
   

4. Build the software:

   make
   

5. Install the software:

   make install
   

   Depending on configuration options and file-system permissions, you may need super-user privileges to do the installation steps.

6. Build the documentation:

   cd ../doc
   ./configure
   make
   

7. Install the documentation:

   make install-info install-html install-pdf
   

   Depending on configuration options and file-system permissions, you may need super-user privileges to do the installation step.

Plugins

After you have installed Scheme you may want to install several plugins. Scheme no longer uses dynamically loaded microcode modules installed with Scheme. The micromodules have been converted into plugins: new subsystems that use the C/FFI to dynamically load the same code. Instead you configure, build, and install additional plugins after installing the core system.

By default, the following plugins are built and installed: edwin, imail, x11, and x11-screen. (The latter two only if X11 libraries are installed on your system.) To get all of the functionality previously available in version 9.2 you will need to build and install the remaining plugins included in the src subdirectory: blowfish, gdbm, and pgsql. These plugins are all configured, built, and installed in the GNU standard way. See the README file in each plugin’s source directory for complete details.

Cleanup

After installing Scheme and your desired plugins, you can delete the source directory:

cd ../..
rm -rf mit-scheme-VERSION

2.1 Basics of Starting Scheme

Under unix, MIT/GNU Scheme is invoked by typing

mit-scheme

at your operating system’s command interpreter. In either case, Scheme will load itself and print something like this:

Copyright (C) 2019 Massachusetts Institute of Technology
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Image saved on Tuesday May 26, 2020 at 10:23:04 PM
  Release 10.90 || SF || LIAR/x86-64

This information, which can be printed again by evaluating

(identify-world)

tells you the following version information. ‘Release’ is the release number for the entire Scheme system. This number is changed each time a new version of Scheme is released.

Following this there may be additional names for specific subsystems. ‘SF’ refers to the scode optimization program sf; ‘LIAR/ARCH’ is the native-code compiler, where ARCH is the native-code architecture it compiles to; ‘Edwin’ is the Emacs-like text editor. There are other subsystems you can load that will add themselves to this list.

2.2 Customizing Scheme

You can customize your setup by using a variety of tools:

• Command-line options. Many parameters, like memory usage and the location of libraries, may be varied by command-line options. See Command-Line Options.
• Shell scripts. You might like to write scripts that invoke Scheme with your favorite command-line options. For example, you might not have enough memory to run Edwin or the compiler with its default memory parameters (it will print something like “Not enough memory for this configuration” and halt when started), so you can write a shell script that will invoke Scheme with the appropriate --heap and other parameters.
• Scheme supports init files: an init file is a file containing Scheme code that is loaded when Scheme is started, immediately after the identification banner, and before the input prompt is printed. This file is stored in your home directory, which is normally specified by the HOME environment variable. Under unix, the file is called .scheme.init.

  In addition, when Edwin starts up, it loads a separate init file from your home directory into the Edwin environment. This file is called .edwin under unix (see Starting Edwin).

  You can use both of these files to define new procedures or commands, or to change defaults in the system.

  The --no-init-file command-line option causes Scheme to ignore the .scheme.init file (see Command-Line Options).

• Environment variables. Most microcode parameters, and some runtime system and Edwin parameters, can be specified by means of environment variables. See Environment Variables.
• Icons. With some window managers under X11, it is possible to create icons that invoke Scheme with different parameters.

2.3 Memory Usage

Some of the parameters that can be customized determine how much memory Scheme uses and how that memory is used. This section describes how Scheme’s memory is organized and used; subsequent sections describe command-line options and environment variables that you can use to customize this usage for your needs.

Scheme uses four kinds of memory:

• A stack that is used for recursive procedure calls.
• A heap that is used for dynamically allocated objects, like cons cells and strings. Storage used for objects in the heap that become unreferenced is eventually reclaimed by garbage collection.
• A constant space that is used for allocated objects, like the heap. Unlike the heap, storage used for objects in constant space is not reclaimed by garbage collection; any unreachable objects in constant space remain there until the Scheme process is terminated. Constant space is used for objects that are essentially permanent, like procedures in the runtime system. Doing this reduces the expense of garbage collection because these objects are no longer copied.
• Some extra storage that is used by the microcode (the part of the system that is implemented in C).

All kinds of memory except the last may be controlled either by command-line options or by environment variables.

MIT/GNU Scheme uses a two-space copying garbage collector for reclaiming storage in the heap. The second space, used only during garbage collection, is dynamically allocated as needed.

Once the storage is allocated for the constant space and the heap, Scheme will dynamically adjust the proportion of the total that is used for constant space; the stack and extra microcode storage is not included in this adjustment. Previous versions of MIT/GNU Scheme needed to be told the amount of constant space that was required when loading bands with the --band option. Dynamic adjustment of the heap and constant space avoids this problem.

If the size of the constant space is not specified, it is automatically set to the correct size for the band being loaded; it is rarely necessary to explicitly set the size of the constant space. Additionally, each band requires a small amount of heap space; this amount is added to any specified heap size, so that the specified heap size is the amount of free space available.

The Scheme expression ‘(print-gc-statistics)’ shows how much heap and constant space is available (see Garbage Collection).

2.4 Command-Line Options

Scheme accepts the command-line options detailed in the following sections. The options may appear in any order, with the restriction that the microcode options must appear before the runtime options, and the runtime options must appear before any other arguments on the command line. Any arguments other than these options will generate a warning message when Scheme starts. If you want to define your own command-line options, see Custom Command-line Options.

Note that MIT/GNU Scheme supports only long options, that is, options specified by verbose names, as opposed to short options, which are specified by single characters. All options start with two hyphens, for compatibility with GNU coding standards (and most modern programs).

These are the microcode options:

--band filename ¶

Specifies the initial world image file (band) to be loaded. Searches for filename in the working directory and the library directories, using the full pathname of the first readable file of that name. If filename is an absolute pathname (on unix, this means it starts with /), then no search occurs—filename is tested for readability and then used directly. If this option isn’t given, the filename is the value of the environment variable MITSCHEME_BAND, or if that isn’t defined, all.com; in these cases the library directories are searched, but not the working directory.

--heap blocks ¶

Specifies the size of the heap in 1024-word blocks. Overrides any default. The size specified by this option is incremented by the amount of heap space needed by the band being loaded. Consequently, --heap specifies how much free space will be available in the heap when Scheme starts, independent of the amount of heap already consumed by the band.

--constant blocks ¶

Specifies the size of constant space in 1024-word blocks. Overrides any default. Constant space holds the compiled code for the runtime system and other subsystems.

--stack blocks ¶

Specifies the size of the stack in 1024-word blocks. Overrides any default. This is Scheme’s stack, not the unix stack used by C programs.

--option-summary ¶

Causes Scheme to write an option summary to standard error. This shows the values of all of the settable microcode option variables.

--emacs ¶

Specifies that Scheme is running as a subprocess of GNU Emacs. This option is automatically supplied by GNU Emacs, and should not be given under other circumstances.

--interactive ¶

If this option isn’t specified, and Scheme’s standard I/O is not a terminal, Scheme will detach itself from its controlling terminal, which prevents it from getting signals sent to the process group of that terminal. If this option is specified, Scheme will not detach itself from the controlling terminal.

This detaching behavior is useful for running Scheme as a background job. For example, using Bourne shell, the following will run Scheme as a background job, redirecting its input and output to files, and preventing it from being killed by keyboard interrupts or by logging out:

mit-scheme < /usr/cph/foo.in > /usr/cph/foo.out 2>&1 &

This option is ignored under non-unix operating systems.

--nocore ¶

Specifies that Scheme should not generate a core dump under any circumstances. If this option is not given, and Scheme terminates abnormally, you will be prompted to decide whether a core dump should be generated.

This option is ignored under non-unix operating systems.

--library path ¶

Sets the library search path to path. This is a list of directories that is searched to find various library files, such as bands. If this option is not given, the value of the environment variable MITSCHEME_LIBRARY_PATH is used; if that isn’t defined, the default is used.

On unix, the elements of the list are separated by colons, and the default value is /usr/local/lib/mit-scheme-ARCH.

--fasl filename ¶

Specifies that a cold load should be performed, using filename as the initial file to be loaded. If this option isn’t given, a normal load is performed instead. This option may not be used together with the --band option. This option is useful only for maintenance and development of the MIT/GNU Scheme runtime system.

The following options are runtime options. They are processed after the microcode options and after the image file is loaded.

--no-init-file ¶

This option causes Scheme to ignore the ${HOME}/.scheme.init file, normally loaded automatically when Scheme starts (if it exists).

--suspend-file ¶

Under some circumstances Scheme can write out a file called scheme_suspend in the user’s home directory.¹ This file is a world image containing the complete state of the Scheme process; restoring this file continues the computation that Scheme was performing at the time the file was written.

Normally this file is never written, but the --suspend-file option enables writing of this file.

--eval expression … ¶

This option causes Scheme to evaluate the expressions following it on the command line, up to but not including the next argument that starts with a hyphen. The expressions are evaluated in the user-initial-environment. Unless explicitly handled, errors during evaluation are silently ignored.

--load file … ¶

This option causes Scheme to load the files (or lists of files) following it on the command line, up to (but not including) the next argument that starts with a hyphen. The files are loaded in the user-initial-environment. Unless explicitly handled, errors during loading are silently ignored.

--edit ¶

This option causes Edwin to be loaded and started immediately when Scheme is started.

The following options allow arguments to be passed to scripts via the command-line-arguments procedure.

procedure: command-line-arguments ¶

Returns a list of arguments (strings) gathered from the command-line by options like --args or --.

--args argument … ¶

This option causes Scheme to append the arguments, up to (but not including) the next argument that starts with a hyphen, to the list returned by the command-line-arguments procedure.

-- argument … ¶

This option causes Scheme to append the rest of the command-line arguments (even those starting with a hyphen) to the list returned by the command-line-arguments procedure.

2.5 Custom Command-line Options

MIT/GNU Scheme provides a mechanism for you to define your own command-line options. This is done by registering handlers to identify particular named options and to process them when Scheme starts. Unfortunately, because of the way this mechanism is implemented, you must define the options and then save a world image containing your definitions (see World Images). Later, when you start Scheme using that world image, your options will be recognized.

The following procedures define command-line parsers. In each, the argument keyword defines the option that will be recognized on the command line. The keyword must be a string containing at least one character; do not include the leading hyphens.

procedure: simple-command-line-parser keyword thunk [help] ¶

Defines keyword to be a simple command-line option. When this keyword is seen on the command line, it causes thunk to be executed. Help, when provided, should be a string describing the option in the --help output.

procedure: argument-command-line-parser keyword multiple? procedure [help] ¶

Defines keyword to be a command-line option that is followed by one or more command-line arguments. Procedure is a procedure that accepts one argument; when keyword is seen, it is called once for each argument. Help, when provided, should be a string describing the option. It is included in the --help output. When not provided, --help will say something lame about your command line option.

Multiple?, if true, says that keyword may be followed by more than one argument on the command line. In this case, procedure is called once for each argument that follows keyword and does not start with a hyphen. If multiple? is #f, procedure is called once, with the command-line argument following keyword. In this case, it does not matter if the following argument starts with a hyphen.

procedure: set-command-line-parser! keyword procedure ¶

This low-level procedure defines keyword to be a command-line option that is defined by procedure. When keyword is seen, procedure is called with all of the command-line arguments, starting with keyword, as a single list argument. Procedure must return two values (using the values procedure): the unused command-line arguments (as a list), and either #f or a thunk to invoke after the whole command line has been parsed (and the init file loaded). Thus procedure has the option of executing the appropriate action at parsing time, or delaying it until after the parsing is complete. The execution of the procedures (or their associated delayed actions) is strictly left-to-right, with the init file loaded between the end of parsing and the delayed actions.

2.6 Environment Variables

Scheme refers to many environment variables. This section lists these variables and describes how each is used. The environment variables are organized according to the parts of MIT/GNU Scheme that they affect.

Environment variables that affect the microcode must be defined before you start Scheme; others can be defined or overwritten within Scheme by using the set-environment-variable! procedure, e.g.

(set-environment-variable! "EDWIN_FOREGROUND" "32")

• Environment Variables for the Microcode
• Environment Variables for the Runtime System
• Environment Variables for Edwin

2.7 Leaving Scheme

There are several ways that you can leave Scheme: there are two Scheme procedures that you can call; there are several Edwin commands that you can execute; and there are graphical-interface buttons (and their associated keyboard accelerators) that you can activate.

• Two Scheme procedures that you can call. The first is to evaluate

  (exit)
  

  which will halt the Scheme system, after first requesting confirmation. Any information that was in the environment is lost, so this should not be done lightly.

  The second procedure suspends Scheme; when this is done you may later restart where you left off. Unfortunately this is not possible in all operating systems; currently it works under unix versions that support job control (i.e. all of the unix versions for which we distribute Scheme). To suspend Scheme, evaluate

  (quit)
  

  If your system supports suspension, this will cause Scheme to stop, and you will be returned to the shell. Scheme remains stopped, and can be continued using the job-control commands of your shell. If your system doesn’t support suspension, this procedure does nothing. (Calling the quit procedure is analogous to typing C-z, but it allows Scheme to respond by typing a prompt when it is unsuspended.)

• Several Edwin commands that you can execute, including save-buffers-kill-scheme, normally bound to C-x C-c, and suspend-scheme, normally bound to C-x C-z. These two commands correspond to the procedures exit and quit, respectively.
• Graphical-interface buttons that you can activate. Under any operating system, closing an Edwin window causes that window to go away, and if it is the only Edwin window, it terminates Scheme as well.

3.1 The Read-Eval-Print Loop

When you first start up Scheme from the command line, you will be typing at a program called the Read-Eval-Print Loop (abbreviated REPL). It displays a prompt at the left hand side of the screen whenever it is waiting for input. You then type an expression (terminating it with RET). Scheme evaluates the expression, prints the result, and gives you another prompt.

• The Prompt and Level Number
• Interrupting
• Restarting
• The Current REPL Environment
• REPL Escapes

1 ]=>

;Unbound variable: foo
;To continue, call RESTART with an option number:
; (RESTART 3) => Specify a value to use instead of foo.
; (RESTART 2) => Define foo to a given value.
; (RESTART 1) => Return to read-eval-print level 1.

2 error>

(nearest-repl/environment)

(procedure-environment procedure)

,(help p)
-| ;,pop
-| ;    Pops an environment off the stack and moves the REPL there.
-| ;,push
-| ;,(push env)
-| ;    Push the REPL env on the env stack and move the REPL to a new env.
-| ;    
-| ;    If ENV is provided, it is converted to an environment in the usual
-| ;    way.  The the current REPL env is pushed on the env stack and the REPL
-| ;    is moved to ENV.
-| ;    
-| ;    If ENV is not provided, the current REPL env is exchanged with the top
-| ;    of the env stack.

3.2 Loading Files

To load files of Scheme code, use the procedure load:

procedure: load filename [environment [syntax-table [purify?]]] ¶

Filename may be a string naming a file, or a list of strings naming multiple files. Environment, if given, is the environment to evaluate the file in; if not given the current REPL environment is used.

Syntax-table is no longer used and if supplied will be ignored.

The optional argument purify? is a boolean that says whether to move the contents of the file into constant space after it is loaded but before it is evaluated. This is performed by calling the procedure purify (see Garbage Collection). If purify? is given and true, this is done; otherwise it is not.

load determines whether the file to be loaded is binary or source code, and performs the appropriate action. By convention, files of source code have names ending in .scm, and files of binary SCode have names ending in .bin. Native-code binaries have names ending in .com. R7RS library files conventionally end in .sld, .binld, and .comld respectively.

If no file-name suffix is specified, load will choose a file by trying different suffixes, preferring in order native-code binaries, SCode binaries, and source files.

All file names are interpreted relative to a working directory, which is initialized when Scheme is started. The working directory can be obtained by calling the procedure pwd or modified by calling the procedure cd; see Working Directory in MIT/GNU Scheme Reference Manual.

procedure: load-option symbol [no-error?] ¶

Loads the option specified by symbol; if already loaded, does nothing. Returns symbol; if there is no such option, an error is signalled. However, if no-error? is specified and true, no error is signalled in this case, and #f is returned.

A number of built-in options are defined:

compress

Support to compress and uncompress files. Undocumented; see the source file runtime/cpress.scm. Used by the runtime system for compression of compiled-code debugging information.

format

The format procedure. See Format in MIT/GNU Scheme Reference Manual.

gdbm

Support to access gdbm databases. Undocumented; see the source files runtime/gdbm.scm and microcode/prgdbm.c.

ordered-vector

Support to search and do completion on vectors of ordered elements. Undocumented; see the source file runtime/ordvec.scm.

regular-expression

Support to search and match strings for regular expressions. See Regular Expressions in MIT/GNU Scheme Reference Manual.

stepper

Support to step through the evaluation of Scheme expressions. Undocumented; see the source file runtime/ystep.scm. Used by the Edwin command step-expression.

subprocess

Support to run other programs as subprocesses of the Scheme process. Undocumented; see the source file runtime/process.scm. Used extensively by Edwin.

synchronous-subprocess

Support to run synchronous subprocesses. See Subprocesses in MIT/GNU Scheme Reference Manual.

In addition to the built-in options, you may define other options to be loaded by load-options by modifying the file optiondb.scm on the library path. An example file is included with the distribution; normally this file consists of a series of calls to the procedure define-load-option, terminated by the expression

(further-load-options standard-load-options)

procedure: define-load-option symbol thunk … ¶

Each thunk must be a procedure of no arguments. Defines the load option named symbol. When the procedure load-option is called with symbol as an argument, the thunk arguments are executed in order from left to right.

3.3 World Images

A world image, also called a band, is a file that contains a complete Scheme system, perhaps additionally including user application code. Scheme provides a method for saving and restoring world images. The method writes a file containing all of the Scheme code and data in the running process. The file all.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)’, 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.

3.4 Garbage Collection

This section describes procedures that control garbage collection. See Memory Usage, for a discussion of how MIT/GNU Scheme uses memory.

procedure: gc-flip [safety-margin] ¶

Forces a garbage collection to occur. Returns the number of words of storage available after collection, an exact non-negative integer.

Safety-margin determines the number of words of storage available to system tasks after the need for a garbage collection is detected and before the garbage collector is started. (An example of such a system task is changing the run-light to show “gc” when scheme is running under Emacs.) Caution: You should not specify safety-margin unless you know what you are doing. If you specify a value that is too small, you can put Scheme in an unusable state.

procedure: purify object [pure-space? [queue?]] ¶

Moves object from the heap into constant space. Has no effect if object is already stored in constant space. Object is moved in its entirety; if it is a compound object such as a list, a vector, or a record, then all of the objects that object points to are also moved to constant space. See Memory Usage.

The optional argument pure-space? is obsolete; it defaults to #t and when explicitly specified should always be #t.

The optional argument queue?, if #f, specifies that object should be moved to constant space immediately; otherwise object is queued to be moved during the next garbage collection. This argument defaults to #t. The reason for queuing these requests is that moving an object to constant space requires a garbage collection to occur, a relatively slow process. By queuing the requests, this overhead is avoided, because moving an object during a garbage collection has minimal effect on the time of the garbage collection. Furthermore, if several requests are queued, they can all be processed together in one garbage collection, while if done separately they would each require their own garbage collection.

procedure: flush-purification-queue! ¶

Forces any pending queued purification requests to be processed. This examines the purify queue, and if it contains any requests, forces a garbage collection to process them. If the queue is empty, does nothing.

procedure: print-gc-statistics ¶

Prints out information about memory allocation and the garbage collector. The information is printed to the current output port. Shows how much space is “in use” and how much is “free”, separately for the heap and constant space. The amounts are shown in words, and also in 1024-word blocks; the block figures make it convenient to use these numbers to adjust the arguments given to the --heap and --constant command-line options. Following the allocation figures, information about the most recent 8 garbage collections is shown, in the same format as a GC notification.

Note that these numbers are accurate at the time that print-gc-statistics is called. In the case of the heap, the “in use” figure shows how much memory has been used since the last garbage collection, and includes all live objects as well as any uncollected garbage that has accumulated since then. The only accurate way to determine the size of live storage is to subtract the value of ‘(gc-flip)’ from the size of the heap. The size of the heap can be determined by adding the “in use” and “free” figures reported by print-gc-statistics.

(print-gc-statistics)
constant in use:   2302316 words =   2248 blocks +  364 words
constant free:         128 words =      0 blocks +  128 words
heap in use:       1747805 words =   1706 blocks +  861 words
heap free:        49682723 words =  48518 blocks +  291 words

procedure: set-gc-notification! [on?] ¶

Controls whether the user is notified of garbage collections. If on? is true, notification is enabled; otherwise notification is disabled. If on? is not given, it defaults to #t. When Scheme starts, notification is disabled.

The notification appears as a single line like the following, showing how many garbage collections have occurred, the time taken to perform the garbage collection and the free storage remaining (in words) after collection.

GC #5: took: 0.50 (8%) CPU time, 0.70 (2%) real time; free: 364346

To operate comfortably, the amount of free storage after garbage collection should be a substantial proportion of the heap size. If the CPU time percentage is consistently high (over 20%), you should consider running with a larger heap. A rough rule of thumb to halve the GC overhead is to take the amount of free storage, divide by 1000, and add this figure to the current value used for the --heap command-line option. Unfortunately there is no way to adjust the heap size without restarting Scheme.

procedure: toggle-gc-notification! ¶

Toggles GC notification on and off. If GC notification is turned on, turns it off; otherwise turns it on.

4.1 Compilation Procedures

procedure: cf filename [destination] ¶

This is the program that transforms a source-code file into native-code binary form. If destination is not given, as in

(cf "foo")

cf compiles the file foo.scm, producing the file foo.com. It will also produce foo.bin, foo.bci, and possibly foo.ext. The corresponding names for R7RS libraries are foo.sld, foo.comld, foo.binld, and foo.bcild (libraries never generate .ext files). If you later evaluate

(load "foo")

foo.com (or foo.comld) will be loaded.

If destination is given, it says where the output files should go. If this argument is a directory, they go in that directory, e.g.:

(cf "foo" "../bar/")

will take foo.scm and generate the file ../bar/foo.com. If destination is not a directory, it is the root name of the output:

(cf "foo" "bar")

takes foo.scm and generates bar.com.

About the .bci files: these files contain the debugging information that Scheme uses when you call debug to examine compiled code. When you load a .com file, Scheme remembers where it was loaded from, and when the debugger (or pp) looks at the compiled code from that file, it attempts to find the .bci file in the same directory from which the .com file was loaded. Thus it is a good idea to leave these files together.

variable: load-debugging-info-on-demand? ¶

If this variable is #f, then printing a compiled procedure will print the procedure’s name only if the debugging information for that procedure is already loaded. Otherwise, it will force loading of the debugging information.

The default value is #f.

procedure: sf filename [destination] ¶

sf is the program that transforms a source-code file into binary SCode form; it is used on machines that do not support native-code compilation. It performs numerous optimizations that can make your programs run considerably faster than unoptimized interpreted code. Also, the binary files that it generates load very quickly compared to source-code files.

The simplest way to use sf is just to say:

(sf filename)

This will cause your file to be transformed, and the resulting binary file to be written out with the same name, but with the suffix .bin. If you do not specify a suffix on the input file, .scm is assumed.

Like load, the first argument to sf may be a list of filenames rather than a single filename.

sf takes an optional second argument, which is the filename of the output file. If this argument is a directory, then the output file has its normal name but is put in that directory instead.

4.2 Declarations

Several declarations can be added to your programs to help cf and sf make them more efficient.

• Standard Names
• In-line Coding
• Operator Replacement
• Operator Reduction

(declare (usual-integrations))

(declare (usual-integrations car cdr cons))

(eval '(sort (append usual-integrations/constant-names
                     usual-integrations/expansion-names)
             (lambda (x y)
               (string<=? (symbol->string x)
                          (symbol->string y))))
      (->environment '(scode-optimizer)))

(define-integrable (foo-bar foo bar)
  (vector-ref (vector-ref foo bar) 3))

(declare (integrate-operator foo-bar))
(define (foo-bar foo bar)
  (declare (integrate foo bar))
  (vector-ref (vector-ref foo bar) 3))

(foo-bar (car baz) (cdr baz))

((lambda (foo bar)
   (declare (integrate foo bar))
   (vector-ref (vector-ref foo bar) 3))
 (car baz)
 (cdr baz))

((lambda (foo bar)
   (vector-ref (vector-ref (car baz) (cdr baz)) 3))
 (car baz)
 (cdr baz))

((lambda ()
   (vector-ref (vector-ref (car baz) (cdr baz)) 3)))

(vector-ref (vector-ref (car baz) (cdr baz)) 3)

(sf "foo.scm")
(pp (fasload "foo.bin"))

(declare (replace-operator (map (2 map-2) (3 map-3))))

(map f x y z) → (map f x y z)
(map f x y) → (map-3 f x y)
(map f x) → (map-2 f x)
(map f) → (map f)
(map) → (map)

(declare (reduce-operator (cons* cons)))

(cons* x y z w) → (cons x (cons y (cons z w))),
(cons* x y) → (cons x y)
(cons* x) → x
(cons*) error→ too few arguments

(declare (reduce-operator (list cons (null-value '() any))))

(list x y z w) → (cons x (cons y (cons z (cons w '()))))
(list x y) → (cons x (cons y '()))
(list x) → (cons x '())
(list) → '()

(declare (reduce-operator (- %- (null-value 0 single) (group left))))

(- x y z w) → (%- (%- (%- x y) z) w)
(- x y) → (%- x y)
(- x) → (%- 0 x)
(-) → 0

(declare (reduce-operator (+ %+ (null-value 0 none) (group right))))

(+ x y z w) → (%+ x (%+ y (%+ z w)))
(+ x y) → (%+ x y)
(+ x) → x
(+) → 0

(declare (reduce-operator (apply (primitive cons)
                                 (group right)
                                 (wrapper (global apply) 1))))

(apply f x y z w)
   → ((access apply #f) f (cons x (cons y (cons z w))))
(apply f x y)
   → ((access apply #f) f (cons x y))
(apply f x) → (apply f x)
(apply f) → (apply f)
(apply) → (apply)

4.3 Efficiency Tips

How you write your programs can have a large impact on how efficiently the compiled program runs. The most important thing to do, after choosing suitable data structures, is to put the following declaration near the beginning of the file.

(declare (usual-integrations))

Without this declaration the compiler cannot recognize any of the common operators and compile them efficiently.

The usual-integrations declaration is usually sufficient to get good quality compiled code.

If you really need to squeeze more performance out of your code then we hope that you find the following grab-bag of tips, hints and explanations useful.

• Coding style
• Top-level variables
• Type and range checking
• Fixnum arithmetic
• Flonum arithmetic

(define (map f lst)
  (if (null? lst)
      '()
      (cons (f (car lst)) (map f (cdr lst)))))

(define (map f lst)
  (cond ((pair? lst)
         (cons (f (car lst)) (map f (cdr lst))))
        ((null? lst)
         '())
        (else
         (error "Not a proper list:"  lst))))

(define (map f original-lst)
  (let walk ((lst original-lst))
    (cond ((pair? lst)
           (cons (f (car lst)) (walk (cdr lst))))
          ((null? lst)
           '())
          (else
           (error "Not a proper list:"  original-lst)))))

(define (f1)
  (define v 100)
  (lambda () v))

(define (f2)
  (define v (compute-100))
  (lambda () v))

(define keep)

(define (compute-100)
  (call-with-current-continuation
   (lambda (k)
     (set! keep k)
     100)))

(define p (f2))

(p)                ⇒ 100
(keep -999)        ⇒ p     re-define v and p
(p)                ⇒ -999

(define x 'something)
(define x (lambda (…) …))
(define (f u v) …)

(set! newline my-better-newline)

(declare (usual-integrations) (integrate-operator %increment!))
(define (%increment! v i)
  (declare (no-type-checks) (no-range-checks))
  (flo:vector-set! v i (flo:+ (flo:vector-ref v i) 1.)))

(define (distance x y)
  (sqrt (+ (* x x) (* y y))))

(define (flo:distance x y)
  (flo:sqrt (flo:+ (flo:* x x) (flo:* y y))))

(flo:vector-set! v 0 (flo:+ (flo:vector-ref v 0) 1.2))

(define (g i)
  (flo:vector-ref v i))

(define (f1 a) (flo:+ a 1))
(define (f2 a) (flo:+ a 1.))

5.1 Subproblems and Reductions

Understanding the concepts of reduction and subproblem is essential to good use of the debugging tools. The Scheme interpreter evaluates an expression by reducing it to a simpler expression. In general, Scheme’s evaluation rules designate that evaluation proceeds from one expression to the next by either starting to work on a subexpression of the given expression, or by reducing the entire expression to a new (simpler, or reduced) form. Thus, a history of the successive forms processed during the evaluation of an expression will show a sequence of subproblems, where each subproblem may consist of a sequence of reductions.

For example, both ‘(+ 5 6)’ and ‘(+ 7 9)’ are subproblems of the following combination:

(* (+ 5 6) (+ 7 9))

If ‘(prime? n)’ is true, then ‘(cons 'prime n)’ is a reduction for the following expression:

(if (prime? n)
    (cons 'prime n)
    (cons 'not-prime n))

This is because the entire subproblem of the if expression can be reduced to the problem ‘(cons 'prime n)’, once we know that ‘(prime? n)’ is true; the ‘(cons 'not-prime n)’ can be ignored, because it will never be needed. On the other hand, if ‘(prime? n)’ were false, then ‘(cons 'not-prime n)’ would be the reduction for the if expression.

The subproblem level is a number representing how far back in the history of the current computation a particular evaluation is. Consider factorial:

(define (factorial n)
  (if (< n 2)
      1
      (* n (factorial (- n 1)))))

If we stop factorial in the middle of evaluating ‘(- n 1)’, the ‘(- n 1)’ is at subproblem level 0. Following the history of the computation “upwards,” ‘(factorial (- n 1))’ is at subproblem level 1, and ‘(* n (factorial (- n 1)))’ is at subproblem level 2. These expressions all have reduction number 0. Continuing upwards, the if expression has reduction number 1.

Moving backwards in the history of a computation, subproblem levels and reduction numbers increase, starting from zero at the expression currently being evaluated. Reduction numbers increase until the next subproblem, where they start over at zero. The best way to get a feel for subproblem levels and reduction numbers is to experiment with the debugging tools, especially debug.

5.2 The Command-Line Debugger

There are two debuggers available with MIT/GNU Scheme. One of them runs under Edwin, and is described in that section of this document (see The Edwin Debugger). The other is command-line oriented, does not require Edwin, and is described here.

The command-line debugger, called debug, is the tool you should use when Scheme signals an error and you want to find out what caused the error. When Scheme signals an error, it records all the information necessary to continue running the Scheme program that caused the error; the debugger provides you with the means to inspect this information. For this reason, the debugger is sometimes called a continuation browser.

Here is the transcript of a typical Scheme session, showing a user evaluating the expression ‘(fib 10)’, Scheme responding with an unbound variable error for the variable fob, and the user starting the debugger:

1 ]=> (fib 10)

;Unbound variable: fob
;To continue, call RESTART with an option number:
; (RESTART 3) => Specify a value to use instead of fob.
; (RESTART 2) => Define fob to a given value.
; (RESTART 1) => Return to read-eval-print level 1.

2 error> (debug)

There are 6 subproblems on the stack.

Subproblem level: 0 (this is the lowest subproblem level)
Expression (from stack):
    fob
Environment created by the procedure: FIB
 applied to: (10)
The execution history for this subproblem contains 1 reduction.
You are now in the debugger.  Type q to quit, ? for commands.

3 debug>

This tells us that the error occurred while trying to evaluate the expression ‘fob’ while running ‘(fib 10)’. It also tells us this is subproblem level 0, the first of 6 subproblems that are available for us to examine. The expression shown is marked ‘(from stack)’, which tells us that this expression was reconstructed from the interpreter’s internal data structures. Another source of information is the execution history, which keeps a record of expressions evaluated by the interpreter. The debugger informs us that the execution history has recorded some information for this subproblem, specifically a description of one reduction.

What follows is a description of the commands available in the debugger. To understand how the debugger works, you need to understand that the debugger has an implicit state that is examined and modified by commands. The state consists of three pieces of information: a subproblem, a reduction, and an environment frame. Each of these parts of the implicit state is said to be selected; thus one refers to the selected subproblem, and so forth. The debugger provides commands that examine the selected state, and allow you to select different states.

Here are the debugger commands. Each of these commands consists of a single letter, which is to be typed by itself at the debugger prompt. It is not necessary to type RET after these commands.

Traversing subproblems ¶

The debugger has several commands for traversing the structure of the continuation. It is useful to think of the continuation as a two-dimensional structure: a backbone consisting of subproblems, and associated ribs consisting of reductions. The bottom of the backbone is the most recent point in time; that is where the debugger is positioned when it starts. Each subproblem is numbered, with 0 representing the most recent time point, and ascending integers numbering older time points. The u command moves up to older points in time, and the d command moves down to newer points in time. The g command allows you to select a subproblem by number, and the h command will show you a brief summary of all of the subproblems.

Traversing reductions ¶

If the subproblem description says that ‘The execution history for this subproblem contains N reductions’, then there is a “rib” of reductions for this subproblem. You can see a summary of the reductions for this subproblem using the r command. You can move to the next reduction using the b command; this moves you to the next older reduction. The f command moves in the opposite direction, to newer reductions. If you are at the oldest reduction for a given subproblem and use the b command, you will move to the next older subproblem. Likewise, if you are at the newest reduction and use f, you’ll move to the next newer subproblem.

Examining subproblems and reductions ¶

The following commands will show you additional information about the currently selected subproblem or reduction. The t command will reprint the standard description (in case it has scrolled off the screen). The l command will pretty-print (using pp) the subproblem’s expression.

Traversing environments

Nearly all subproblems and all reductions have associated environments. Selecting a subproblem or reduction also selects the associated environment. However, environments are structured as a sequence of frames, where each frame corresponds to a block of environment variables, as bound by lambda or let. These frames collectively represent the block structure of a given environment.

Once an environment frame is selected by the debugger, it is possible to select the parent frame of that frame (in other words, the enclosing block) using the p command. You can subsequently return to the original child frame using the s command. The s command works because the p command keeps track of the frames that you step through as you move up the environment hierarchy; the s command just retraces the path of saved frames. Note that selecting a frame using p or s will print the bindings of the newly selected frame.

Examining environments ¶

The following commands allow you to examine the contents of the selected frame. The c command prints the bindings of the current frame. The a command prints the bindings of the current frame and each of its ancestor frames. The e command enters a read-eval-print loop in the selected environment frame; expressions typed at that REPL will be evaluated in the selected environment. To exit the REPL and return to the debugger, evaluate ‘(abort->previous)’ or use restart. The v command prompts for a single expression and evaluates it in the selected environment. The w command invokes the environment inspector (where); quitting the environment inspector returns to the debugger. Finally, the o command pretty-prints the procedure that was called to create the selected environment frame.

Continuing the computation ¶

There are three commands that can be used to restart the computation that you are examining. The first is the k command, which shows the currently active restarts, prompts you to select one, and passes control to the it. It is very similar to evaluating ‘(restart)’.

The other two commands allow you to invoke internal continuations. This should not be done lightly; invoking an internal continuation can violate assumptions that the programmer made and cause unexpected results. Each of these commands works in the same way: it prompts you for an expression, which is evaluated in the selected environment to produce a value. The appropriate internal continuation is then invoked with that value as its sole argument. The two commands differ only in which internal continuation is to be invoked.

The j command invokes the continuation associated with the selected subproblem. What this means is as follows: when the description of a subproblem is printed, it consists of two parts, and “expression” and a “subproblem being executed”. The latter is usually marked in the former by the specific character sequence ‘###’. The internal continuation of the subproblem is the code that is waiting for the “subproblem being executed” to return a value. So, in effect, you are telling the program what the “subproblem being executed” will evaluate to, and bypassing further execution of that code.

The z command is slightly different. It instead invokes the continuation that is waiting for the outer “expression” to finish. In other words, it is the same as invoking the j command in the next frame up. So you can think of this as an abbreviation for the u command followed by the j command.

Wizard commands ¶

The m, x, and y commands are for Scheme wizards. They are used to debug the MIT/GNU Scheme implementation. If you want to find out what they do, read the source code.

Miscellaneous commands ¶

The i command will reprint the error message for the error that was in effect immediately before the debugger started. The q command quits the debugger, returning to the caller. And the ? command prints a brief summary of the debugger’s commands.

5.3 Debugging Aids

This section describes additional commands that are useful for debugging.

procedure: bkpt datum argument … ¶

Sets a breakpoint. When the breakpoint is encountered, datum and the arguments are typed (just as for error) and a read-eval-print loop is entered. The environment of the read-eval-print loop is derived by examining the continuation of the call to bkpt; if the call appears in a non-tail-recursive position, the environment will be that of the call site. To exit from the breakpoint and proceed with the interrupted process, call the procedure continue. Sample usage:

1 ]=> (begin (write-line 'foo)
             (bkpt 'test-2 'test-3)
             (write-line 'bar)
             'done)

foo
 test-2 test-3
;To continue, call RESTART with an option number:
; (RESTART 2) => Return from BKPT.
; (RESTART 1) => Return to read-eval-print level 1.

2 bkpt> (+ 3 3)

;Value: 6

2 bkpt> (continue)

bar
;Value: done

procedure: pp object [output-port [as-code?]] ¶

The pp procedure is described in Output Procedures in MIT/GNU Scheme Reference Manual. However, since this is a very useful debugging tool, we also mention it here. pp provides two very useful functions:

1. pp will print the source code of a given procedure. Often, when debugging, you will have a procedure object but will not know exactly what procedure it is. Printing the procedure using pp will show you the source code, which greatly aids identification.
2. pp will print the fields of a record structure. If you have a compound object pointer, print it using pp to see the component fields, like this:

   (pp (->pathname "~"))
   -| #[pathname 14 "/usr/home/cph"]
   -| (host #[host 15])
   -| (device unspecific)
   -| (directory (absolute "usr" "home"))
   -| (name "cph")
   -| (type ())
   -| (version unspecific)
   

   When combined with use of the #@ syntax, pp provides the functionality of a simple object inspector. For example, let’s look at the fields of the host object from the above example:

   (pp #@15)
   -| #[host 15]
   -| (type-index 0)
   -| (name ())
   

procedure: pa procedure ¶

pa prints the arguments of procedure. This can be used to remind yourself, for example, of the correct order of the arguments to a procedure.

for-all?
 ⇒ #[compiled-procedure 40 ("boole" #x6) #xC #x20ECB0]

(pa for-all?)
-| (items predicate)

(pp for-all?)
-|(named-lambda (for-all? items predicate)
-|  (let loop ((items items))
-|    (or (null? items)
-|        (and (predicate (car items))
-|             (loop (cdr items))))))

procedure: where [obj] ¶

The procedure where enters the environment examination system. This allows environments and variable bindings to be examined and modified. where accepts one-letter commands. The commands can be found by typing ? to the ‘where>’ prompt. The optional argument, obj, is an object with an associated environment: an environment, a procedure, or a promise. If obj is omitted, the environment examined is the read-eval-print environment from which where was called (or an error or breakpoint environment if called from the debugger). If a procedure is supplied, where lets the user examine the closing environment of the procedure. This is useful for debugging procedure arguments and values.

procedure: apropos string [environment [search-parents?]] ¶

Search an environment for bound names containing string and print out the matching bound names. If environment is specified, it must be an environment or package name, and it defaults to the current REPL environment. The flag search-parents? specifies whether the environment’s parents should be included in the search. The default is #f if environment is specified, and #t if environment is not specified.

(apropos "search")
-| #[package 12 (user)]
-| #[package 13 ()]
-| alist-table-search
-| re-string-search-backward
-| re-string-search-forward
-| re-substring-search-backward
-| re-substring-search-forward
-| regexp-search
-| regexp-search-all
-| regsexp-search-string-forward
-| search-gc-finalizer
-| search-ordered-subvector
-| search-ordered-vector
-| string-search-all
-| string-search-backward
-| string-search-forward
-| substring-search-all
-| substring-search-backward
-| substring-search-forward
-| vector-binary-search
-| weak-alist-table-search

5.4 Advising Procedures

Giving advice to procedures is a powerful debugging technique. trace and break are useful examples of advice-giving procedures. Note that the advice system only works for interpreted procedures.

procedure: trace-entry procedure ¶

Causes an informative message to be printed whenever procedure is entered. The message is of the form

[Entering #[compound-procedure 1 foo]
    Args: val1
          val2
          …]

where val1, val2 etc. are the evaluated arguments supplied to the procedure.

(trace-entry fib)
(fib 3)
-| [Entering #[compound-procedure 19 fib]
-|     Args: 3]
-| [Entering #[compound-procedure 19 fib]
-|     Args: 1]
-| [Entering #[compound-procedure 19 fib]
-|     Args: 2]
⇒ 3

procedure: trace-exit procedure ¶

Causes an informative message to be printed when procedure terminates. The message contains the procedure, its argument values, and the value returned by the procedure.

(trace-exit fib)
(fib 3)
-| [1
-|       <== #[compound-procedure 19 fib]
-|     Args: 1]
-| [2
-|       <== #[compound-procedure 19 fib]
-|     Args: 2]
-| [3
-|       <== #[compound-procedure 19 fib]
-|     Args: 3]
⇒ 3

procedure: trace-both procedure ¶

procedure: trace procedure ¶

Equivalent to calling both trace-entry and trace-exit on procedure. trace is the same as trace-both.

(trace-both fib)
(fib 3)
-| [Entering #[compound-procedure 19 fib]
-|     Args: 3]
-| [Entering #[compound-procedure 19 fib]
-|     Args: 1]
-| [1
-|       <== #[compound-procedure 19 fib]
-|     Args: 1]
-| [Entering #[compound-procedure 19 fib]
-|     Args: 2]
-| [2
-|       <== #[compound-procedure 19 fib]
-|     Args: 2]
-| [3
-|       <== #[compound-procedure 19 fib]
-|     Args: 3]
⇒ 3

procedure: untrace-entry [procedure] ¶

Stops tracing the entry of procedure. If procedure is not given, the default is to stop tracing the entry of all entry-traced procedures.

procedure: untrace-exit [procedure] ¶

Stops tracing the exit of procedure. If procedure is not given, the default is all exit-traced procedures.

procedure: untrace [procedure] ¶

Stops tracing both the entry to and the exit from procedure. If procedure is not given, the default is all traced procedures.

procedure: break-entry procedure ¶

Like trace-entry with the additional effect that a breakpoint is entered when procedure is invoked. Both procedure and its arguments can be accessed by calling the procedures *proc* and *args*, respectively. Use restart or continue to continue from a breakpoint.

procedure: break-exit procedure ¶

Like trace-exit, except that a breakpoint is entered just prior to leaving procedure. Procedure, its arguments, and the result can be accessed by calling the procedures *proc*, *args*, and *result*, respectively. Use restart or continue to continue from a breakpoint.

procedure: break-both procedure ¶

procedure: break procedure ¶

Sets a breakpoint at the beginning and end of procedure. This is break-entry and break-exit combined.

procedure: unbreak [procedure] ¶

Discontinues the entering of a breakpoint on the entry to and exit from procedure. If procedure is not given, the default is all breakpointed procedures.

procedure: unbreak-entry [procedure] ¶

Discontinues the entering of a breakpoint on the entry to procedure. If procedure is not given, the default is all entry-breakpointed procedures.

procedure: unbreak-exit [procedure] ¶

Discontinues the entering of a breakpoint on the exit from procedure. If procedure is not given, the default is all exit-breakpointed procedures.

The following three procedures are valid only within the dynamic extent of a breakpoint. In other words, don’t call them unless you are stopped inside a breakpoint.

procedure: *proc* ¶

Returns the procedure in which the breakpoint has stopped.

procedure: *args* ¶

Returns the arguments to the procedure in which the breakpoint has stopped. The arguments are returned as a newly allocated list.

procedure: *result* ¶

Returns the result yielded by the procedure in which the breakpoint has stopped. This is valid only when in an exit breakpoint.

The following procedures install advice procedures that are called when the advised procedure is entered or exited. An entry-advice procedure must accept three arguments: the advised procedure, a list of the advised procedure’s arguments, and the advised procedure’s application environment (that is, the environment in which the procedure’s formal parameters are bound). An exit-advice procedure must accept four arguments: the advised procedure, a list of the advised procedure’s arguments, the result yielded by the advised procedure, and the advised procedure’s application environment.

Note that the trace and breakpoint procedures described above are all implemented by means of the more general advice procedures, so removing advice from an advised procedure will also remove traces and breakpoints.

procedure: advise-entry procedure advice ¶

Advice must be an entry-advice procedure. Advice is attached to procedure, so that whenever procedure is entered, advice is called.

procedure: advise-exit procedure advice ¶

Advice must be an exit-advice procedure. Advice is attached to procedure, so that whenever procedure returns, advice is called.

procedure: advice procedure ¶

Returns the advice procedures, if any, that are attached to procedure. This is returned as a list of two lists: the first list is all of the entry-advice procedures attached to procedure, and the second is all of the exit-advice procedures.

procedure: unadvise-entry [procedure] ¶

Removes all entry-advice procedures from procedure. If procedure is not given, the default is all entry-advised procedures.

procedure: unadvise-exit [procedure] ¶

Removes exit-advice procedures from procedure. If procedure is not given, the default is all exit-advised procedures.

procedure: unadvise [procedure] ¶

Removes all advice procedures from procedure. This is a combination of unadvise-entry and unadvise-exit. If procedure is not given, the default is all advised procedures.

8.1 Starting Edwin

To use Edwin, start Scheme with the following command-line options:

mit-scheme --edit

Alternatively, you can load Edwin by calling the procedure edit:

procedure: edit ¶

procedure: edwin ¶

Enter the Edwin text editor. If entering for the first time, the editor is initialized (by calling create-editor with no arguments). Otherwise, the previously-initialized editor is reentered.

The procedure edwin is an alias for edit.

variable: inhibit-editor-init-file? ¶

When Edwin is first initialized, it loads your init file (called ~/.edwin under unix) if you have one. If the Scheme variable inhibit-editor-init-file? is true, however, your init file will not be loaded even if it exists. By default, this variable is false.

Note that you can set this variable in your Scheme init file (see Customizing Scheme).

procedure: create-editor arg … ¶

Initializes Edwin, or reinitializes it if already initialized. create-editor is normally invoked automatically by edit.

If no args are given, the value of create-editor-args is used instead. In other words, the following are equivalent:

(create-editor)
(apply create-editor create-editor-args)

On the other hand, if args are given, they are used to update create-editor-args, making the following equivalent:

(apply create-editor args)
(begin (set! create-editor-args args) (create-editor))

variable: create-editor-args ¶

This variable controls the initialization of Edwin. The following values are defined:

(#f)

This is the default. Creates a window of some default size, and uses that window as Edwin’s main window. Under unix, if X11 is not available or if the DISPLAY environment variable is undefined, Edwin will run on Scheme’s console.

(x)

Unix only. Creates an X window and uses it as Edwin’s main window. This requires the DISPLAY environment variable to have been set to the appropriate value before Scheme was started.

(x geometry)

Unix only. Like ‘(x)’ except that geometry specifies the window’s geometry in the usual way. Geometry must be a character string whose contents is an X geometry specification.

(console)

Unix only. Causes Edwin to run on Scheme’s console, or in unix terminology, the standard input and output. If the console is not a terminal device, or is not powerful enough to run Edwin, an error will be signalled at initialization time.

8.2 Leaving Edwin

Once Edwin has been entered, it can be exited in the following ways:

C-x z ¶

Stop Edwin and return to Scheme (suspend-edwin). The call to the procedure edit that entered Edwin returns normally. A subsequent call to edit will resume Edwin where it was stopped.

C-x c ¶

Offer to save any modified buffers, then kill Edwin, returning to Scheme (save-buffers-kill-edwin). This is like the suspend-edwin command, except that a subsequent call to edit will reinitialize the editor.

C-x C-z ¶

Stop Edwin and suspend Scheme, returning control to the operating system’s command interpreter (suspend-scheme). When Scheme is resumed (using the command interpreter’s job-control commands), Edwin is automatically restarted where it was stopped. This command corresponds to the C-x C-z command of GNU Emacs.

C-x C-c ¶

Offer to save any modified buffers, then kill both Edwin and Scheme (save-buffers-kill-scheme). Control is returned to the operating system’s command interpreter, and the Scheme process is terminated. This command corresponds to the C-x C-c command of GNU Emacs.

8.3 Scheme Mode

As you might expect, Edwin has special support for editing and evaluating Scheme code. This section describes Scheme Mode, the appropriate mode for editing MIT/GNU Scheme programs.

Scheme mode is normally entered automatically by visiting a file whose file name ends in ‘.scm’. You can also mark a file as Scheme code by placing the string ‘-*-Scheme-*-’ on the first line of the file. Finally, you can put any buffer in Scheme mode by executing the command M-x scheme-mode.

Scheme mode is similar to the Emacs modes that edit Lisp code. So, for example, C-i indents the current line, and C-M-q indents the expression to the right of point. The close parenthesis will temporarily flash the matching open parenthesis. Most Scheme constructs requiring special indentation are recognized by Scheme mode, for example, begin, do, and let.

Scheme mode also provides support that is specific to Scheme programs, much as Emacs-Lisp mode does in Emacs. Completion of global variable names is provided: type the first few characters of a variable, then type C-M-i, and Edwin will attempt to complete the variable name using the current set of bound variables. If C-M-i is given a prefix argument, it will complete the name using the current set of interned symbols (which includes the bound variables as a subset).

The M-A command (note the uppercase A) will show the parameters of a procedure when point is inside a procedure call. For example, type the string ‘(quotient’, then press M-A, and the command will echo ‘(n d)’ in the echo area. With a prefix argument, M-A will insert the parameter names in the buffer at point, so in this example, the buffer would contain ‘(quotient n d’ after running C-u M-A.

8.4 Evaluation

Scheme mode also provides commands for evaluating Scheme expressions. The simplest evaluation command is C-x C-e, which evaluates the expression to the left of point. (This key is bound in all buffers, even if they don’t contain Scheme code.) The command M-z evaluates the definition that point is in (a definition is an expression starting with a left parenthesis in the leftmost column). The command M-: prompts for an expression in the minibuffer, evaluates it, and prints the value in the echo area.

Other commands that evaluate larger amounts of code are C-M-z, which evaluates all of the expressions in the region, and M-o, which evaluates the entire buffer. Both of these commands are potentially dangerous in that they will evaluate anything that appears to be an expression, even if it isn’t intended to be.

Normally, these commands evaluate expressions by sending them to a REPL buffer, which performs the evaluations in a separate thread. This has two advantages: it allows you to continue editing while the evaluation is happening, and it keeps a record of each evaluation and its printed output. If you wish to stop a running evaluation and to erase any pending expressions, use the C-c C-c command from any Scheme buffer. (Note that by default, Edwin starts up with one REPL buffer, called ‘*scheme*’.)

If you would prefer to have Scheme mode evaluation commands evaluate directly, rather than sending expressions to the REPL buffer, set the Edwin variable evaluate-in-inferior-repl to #f. In this case, you will not be able to use Edwin while evaluation is occurring; any output from the evaluation will be shown in a pop-up buffer when the evaluation finishes; and you abort the evaluation using C-g.

8.5 REPL Mode

Edwin provides a special mechanism for interacting with Scheme read-eval-print loops: REPL buffers. A REPL buffer is associated with a Scheme REPL running in a separate thread of execution; because of this, expressions may be evaluated in this buffer while you simultaneously do other things with the editor. A REPL buffer captures all printed output from an evaluated expression, as well as supporting interactive programs such as debug. For these and other reasons, REPL buffers are the preferred means for interacting with the Scheme interpreter.

When Edwin starts, it has one buffer: a REPL buffer called ‘*scheme*’. The command M-x repl selects this buffer, if it exists; otherwise it creates a new REPL buffer. If you want two REPL buffers, just rename the ‘*scheme*’ buffer to something else and run M-x repl again.

REPL buffers support all the same evaluation commands that Scheme mode does; in fact, REPL buffers use a special mode called REPL mode that inherits from Scheme mode. Thus, any key bindings defined in Scheme mode are also defined in REPL mode. One exception to this is the M-o command, which is deliberately undefined in REPL mode; otherwise it would be too easy to re-evaluate all the previously evaluated expressions in the REPL buffer.

In addition to evaluation commands, REPL mode provides a handful of special commands for controlling the REPL itself. The commands C-c C-x and C-c C-u abort the current evaluation, returning to the current or previous REPL levels, respectively. The command C-c C-b interrupts the current evaluation, entering a breakpoint.

Each REPL buffer maintains a history of the expressions that were typed into it. Several commands allow you to access the contents of this history. The command M-p moves backwards through the history, inserting previously evaluated expressions at point. Likewise, M-n moves forward through the history. The commands C-c C-r and C-c C-s search backward and forward through the history for a particular string. The command C-c C-o deletes any output from the previous evaluation; use this command with care since it cannot be undone. The command C-c C-l finds the most recent expression in the buffer and moves point there.

When an expression that you evaluate signals an error, the REPL buffer notices this and offers to run the debugger for you. Answer this question with a ‘y’ or ‘n’ response. You can start the debugger whenever the REPL buffer is listening by executing the C-c C-d command. In either case, this starts the Edwin debugger, which pops up a new window containing the debugger. Your REPL buffer remains in the error state, allowing you to examine it further if you wish.

8.6 The Edwin Debugger

The Edwin debugger is similar to the command-line debugger, except that it takes advantage of multiple windows and Edwin’s command structure to provide a more intuitive interface. The debugger operates as a browser, much like Dired, presenting you with an overview of the subproblem structure, and allowing you to examine parts of that structure in more detail by selecting the parts. When started, the debugger creates a buffer ‘*debug*’ showing the subproblem structure, and selects the first line.

Each line beginning with ‘S’ represents either a subproblem or stack frame. A subproblem line may be followed by one or more indented lines (beginning with the letter ‘R’) which represent reductions associated with that subproblem. The subproblems are indexed with the natural numbers. To obtain a more complete description of a subproblem or reduction, click the mouse on the desired line or move the cursor to the line using the arrow keys (or C-n and C-p). The description buffer will display the additional information.

The description buffer contains three major regions. The first region contains a pretty-printed version of the current expression. The current subproblem within the expression is highlighted. The second region contains a representation of the frames of the environment of the current expression. The bindings of each frame are listed below the frame header. If there are no bindings in the frame, none will be listed. The frame of the current expression is preceded with ‘==>’.

The bottom of the description buffer contains a third region for evaluating expressions in the environment of the selected subproblem or reduction. This is the only portion of the buffer where editing is possible. This region can be used to find the values of variables in different environments, or even to modify variable values or data structures (note that variables in compiled code cannot usually be modified).

Typing e creates a new buffer in which you may browse through the current environment. In this new buffer, you can use the mouse, the arrows, or C-n and C-p to select lines and view different environments. The environments listed are the same as those in the description buffer. If the selected environment structure is too large to display (i.e. if the number of bindings in the environment exceeds the value of the editor variable environment-package-limit) a message to that effect is displayed. To display the environment in this case, use M-x set-variable to set environment-package-limit to #f. At the bottom of the new buffer is a region for evaluating expressions, similar to that of the description buffer.

The appearance of environment displays is controlled by the editor variables debugger-show-inner-frame-topmost? and debugger-compact-display? which affect the ordering of environment frames and the line spacing respectively.

Type q to quit the debugger, killing its primary buffer, any others that it has created, and the window that was popped up to show the debugger.

Note: The description buffers created by the debugger are given names beginning with spaces so that they do not appear in the buffer list; these buffers are automatically deleted when you quit the debugger. If you wish to keep one of these buffers, simply rename it using M-x rename-buffer: once it has been renamed, it will not be automatically deleted.

8.7 Last Resorts

When Scheme exits abnormally it tries to save any unsaved Edwin buffers. The buffers are saved in an auto-save file in case the original is more valuable than the unsaved version. You can use the editor command M-x recover-file to recover the auto-saved version. The name used to specify an auto-save file is operating-system dependent: under unix foo.scm will be saved as #foo.scm#.

The following Scheme procedures are useful for recovering from bugs in Edwin’s implementation. All of them are designed for use when Edwin is not running—they should not be used when Edwin is running. These procedures are designed to help Edwin’s implementors deal with bugs during the implementation of the editor; they are not intended for casual use, but as a means of recovering from bugs that would otherwise require reloading the editor’s world image from the disk.

procedure: save-editor-files ¶

Examines Edwin, offering to save any unsaved buffers. This is useful if some bug caused Edwin to die while there were unsaved buffers, and you want to save the information without restarting the editor.

procedure: reset-editor ¶

Resets Edwin, causing it to be reinitialized the next time that edit is called. If you encounter a fatal bug in Edwin, a good way to recover is to first call save-editor-files, and then to call reset-editor. That should completely reset the editor to its initial state.

procedure: reset-editor-windows ¶

Resets Edwin’s display structures, without affecting any of the buffers or their contents. This is useful if a bug in the display code causes Edwin’s internal display data structures to get into an inconsistent state that prevents Edwin from running.