Running Scheme48
================

Scheme48 is run by invoking its virtual machine on a dumped heap image to resume a saved system state.  The common case of invoking the default image, scheme48.image, which contains the usual command processor, run-time system, etc, is what the scheme48 script that is installed does.  The actual virtual machine executable itself, scheme48vm, is typically not installed into an executable directory such as /usr/local/bin/ on Unix, but in the Scheme48 library directory, which is, by default on Unix installations of Scheme48, /usr/local/lib/.  However, both scheme48 and scheme48vm share the following command-line options; the only difference is that scheme48 has a default -i argument.

-h HEAP-SIZE
     The size of Scheme48's heap, in cells.  By default, the heap size is 3 megacells, or 12 megabytes, permitting 6 megabytes per semispace --- Scheme48 uses a simple stop & copy garbage collector. (The Scheme48 team is also working on a new, generational garbage collector, but it is not in the standard distribution of Scheme48 yet.)  Since the current garbage collector cannot resize the heap dynamically if it becomes consistently too full, users on machines with much RAM may be more comfortable with liberally increasing this option.

-s STACK-SIZE
     The stack size, in cells.  The default stack size is 10000 bytes, or 2500 cells.  Note that this is only the size of the stack cache segment of memory for fast stack frame storage.  When this overflows, there is no error; instead, Scheme48 simply copies the contents of the stack cache into the heap, until the frames it copied into the heap are needed later, at which point they are copied back into the stack cache.  The -s option therefore affects only performance, not the probability of fatal stack overflow errors.

-i IMAGE-FILENAME
     The filename of the suspended heap image to resume.  When running the scheme48 executable, the default is the regular Scheme48 image; when running the virtual machine directly, this option must be passed explicitly.  For information on creating custom heap images, see Image-building commands, and also see Suspending and resuming heap images.

-a ARGUMENT ...
     Command-line arguments to pass to the heap image's resumer, rather than being parsed by the virtual machine.  In the usual Scheme48 command processor image, these arguments are put in a list of strings that will be the initial Focus value, focus value.

-u
     Muffles warnings on startup about undefined imported foreign bindings.

The usual Scheme48 image may accept an argument of batch, using the -a switch to the virtual machine.  This enters Scheme48 in batch mode, which displays no welcoming banner, prints no prompt for inputs, and exits when an EOF is read.  This may be used to run scripts from the command-line, often in the Command programs, exec language, by sending text to Scheme48 through Unix pipes or shell heredocs.  For example, this Unix shell command will load the command program in the file foo.scm into the exec language environment and exit Scheme48 when the program returns:

     echo ,exec ,load foo.scm | scheme48 -a batch example

     This Unix shell command will load packages.scm into the module
     language environment, open the tests structure into the user
     environment, and call the procedure run-tests with zero
     arguments:

          scheme48 -a batch <<END
          ,config ,load packages.scm
          ,open tests
          (run-tests)
          END example

          Scheme48 also supports [SRFI 22] and [SRFI 7] by providing R5RS and
          [SRFI 7] script interpreters in the location where Scheme48 binaries
          are kept as scheme-r5rs and scheme-srfi-7.  See the
          [SRFI 22] and [SRFI 7] documents for more details.  Scheme48's command
          processor also has commands for loading [SRFI 7] programs, with or
          without a [SRFI 22] script header; see SRFI 7.

Command processor introduction
------------------------------

The Scheme48 command processor is started up on resumption of the usual Scheme48 image.  This is by default what the scheme48 script installed by Scheme48 does.  It will first print out a banner that contains some general information about the system, which will typically look something like this:

     Welcome to Scheme 48 1.3 (made by root on Sun Jul 10 10:57:03 EDT 2005)
     Copyright (c) 1993-2005 by Richard Kelsey and Jonathan Rees.
     Please report bugs to scheme-48-bugs@s48.org.
     Get more information at http://www.s48.org/.
     Type ,? (comma question-mark) for help. example

     After the banner, it will initiate a REPL (read-eval-print loop).  At
     first, there should be a simple > prompt.  The command processor
     interprets Scheme code as well as commands.  Commands operate the
     system at a level above or outside Scheme.  They begin with a comma, and
     they continue until the end of the line, unless they expect a Scheme
     expression argument, which may continue as many lines as desired.  Here
     is an example of a command invocation:

          > ,set load-noisily on example

          This will set the Command processor switches,
          load-noisily switch on.

          Note: If a command accepts a Scheme expression argument that
          is followed by more arguments, all of the arguments after the Scheme
          expression must be put on the same line as the last line of the Scheme
          expression.

          Certain operations, such as breakpoints and errors, result in a
          recursive command processor to be invoked.  This is known as
          pushing a command level.  See Command levels.  Also, the
          command processor supports an object inspector, an interactive
          program for inspecting the components of objects, including continuation
          or stack frame objects; the debugger is little more than the inspector,
          working on continuations.  See Inspector.

          Evaluation of code takes place in the interaction environment.
          (This is what R5RS's interaction-environment returns.)
          Initially, this is the user environment, which by default is a
          normal R5RS Scheme environment.  There are commands that set the
          interaction environment and evaluate code in other environments, too;
          see Module commands.

          The command processor's prompt has a variety of forms.  As above, it
          starts out with as a simple >.  Several factors can affect the
          prompt.  The complete form of the prompt is as follows:

            * It begins with an optional Command levels, command level
               number: at the top level, there is no command level number; as command
               levels are pushed, the number is incremented, starting at 1.

            * Optionally, the name of the interaction environment follows the
               command level number: if the interaction environment is the user
               environment, there is no name printed here; named environments are
               printed with their names; unnamed environments (usually created using
               the ,new-package command; see Module commands) are
               printed with their numeric identifiers.  If a command level number
               preceded an environment name, a space is printed between them.

            * If the command processor is in the regular REPL mode, it ends with a
               > and a space before the user input area; if it is in
               Inspector, inspector mode, it ends with a : and a
               space before the user input area.

          For example, this prompt denotes that the user is in inspector mode at
          command level 3 and that the interaction environment is an environment
          named frobozz:

               3 frobozz: example

               This prompt shows that the user is in the regular REPL mode at the top
               level, but in the Module commands, environment for module
               descriptions:

                    config> example

                    For a complete listing of all the commands in the command processor,
                    see Command processor.