s48-refman/user/run.texi

@node Running Scheme48
@section Running Scheme48

@cindex heap image resumption
@cindex resuming heap images
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, @file{scheme48.image}, which contains the usual command
processor, run-time system, @etc{}, is what the @command{scheme48}
script that is installed does.  The actual virtual machine executable
itself, @command{scheme48vm}, is typically not installed into an
executable directory such as @file{/usr/local/bin/} on Unix, but in
the Scheme48 library directory, which is, by default on Unix
installations of Scheme48, @file{/usr/local/lib/}.  However, both
@command{scheme48} and @command{scheme48vm} share the following
command-line options; the only difference is that @command{scheme48}
has a default @option{-i} argument.

@table @option
@item -h @var{heap-size}
@cindex heap size
@cindex memory 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.@footnote{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.

@item -s @var{stack-size}
@cindex 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 @option{-s} option therefore affects only performance, not
the probability of fatal stack overflow errors.

@item -i @var{image-filename}
The filename of the suspended heap image to resume.  When running the
@command{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,
@pxref{Image-building commands}, and also @pxref{Suspending and
resuming heap images}.

@item -a @var{argument} @dots{}
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 @embedref{Focus value, focus value}.

@item -u
@cindex undefined imported bindings
Muffles warnings on startup about undefined imported foreign bindings.
@end table

@cindex batch mode
The usual Scheme48 image may accept an argument of @code{batch}, using
the @option{-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 @embedref{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 @file{foo.scm} into the exec
language environment and exit Scheme48 when the program returns:

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

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

@example
scheme48 -a batch <<END
,config ,load packages.scm
,open tests
(run-tests)
END@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 @command{scheme-r5rs} and @command{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; @pxref{SRFI 7}.

@subsection Command processor introduction

The Scheme48 command processor is started up on resumption of the usual
Scheme48 image.  This is by default what the @command{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:

@example
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.@end example

@noindent
After the banner, it will initiate a REPL (read-eval-print loop).  At
first, there should be a simple @samp{>} prompt.  The command processor
interprets Scheme code as well as @dfn{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:

@example
> ,set load-noisily on@end example

@noindent
This will set the @embedref{Command processor switches,
@code{load-noisily} switch} on.

@strong{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
@dfn{pushing a command level}.  @xref{Command levels}.  Also, the
command processor supports an @dfn{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.  @xref{Inspector}.

Evaluation of code takes place in the @dfn{interaction environment}.
(This is what R5RS's @code{interaction-environment} returns.)
Initially, this is the @dfn{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;
@pxref{Module commands}.

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

@itemize @bullet
@item
It begins with an optional @embedref{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.

@item
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 @command{,new-package} command; @pxref{Module commands}) are
printed with their numeric identifiers.  If a command level number
preceded an environment name, a space is printed between them.

@item
If the command processor is in the regular REPL mode, it ends with a
@samp{>} and a space before the user input area; if it is in
@embedref{Inspector, inspector mode}, it ends with a @samp{:} and a
space before the user input area.
@end itemize

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 @code{frobozz}:

@example
3 frobozz: @end example

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

@example
config> @end example

For a complete listing of all the commands in the command processor,
@pxref{Command processor}.