# Installation and Invocation

## Required Environment

&SISC; primarily targets the Java Virtual Machine, and the Java v1.3 and higher class libraries. The 1.2 libraries and VM are required due to a reliance on memory reference functionality used to properly garbage collect unused symbols while still maintaining pointer equality between those that remain active, while the 1.3 libraries are needed for the proxy functionality of the Java bridge library.

&SISC; does not require any particular operating system, though the official distribution currently provides launching assistance for Windows and Unix based systems. Theoretically any machine that supports Java 1.3 or higher should be able to run &SISC;.

## The Read-Eval-Print-Loop

As in most Scheme systems, &SISC;'ss primary human interface is a REPL, or Read-Eval-Print-Loop. &SISC; presents the user with a prompt ('`#;>`'), then reads an s-expression from the console. &SISC; then evaluates the s-expression, producing a value or error, which it then prints. Finally the process begins again with a new prompt.

The process terminates with a forced kill of the JVM (with Control-C or similar), or when an end of file is detected on the console. Also, the `exit` procedure may be used to exit the current REPL.

> &procedure; `does not return` `exit` `return-value`

> > Instructs the current REPL to exit. If the optional return value is given, the value will be passed out of the REPL to the calling code or environment.

Evaluation may be prematurely interrupted on some platforms by sending SIGQUIT (usually by pressing Control-C) to the &SISC; process. If supported, this will cause an interrupted error to be raised at whichever expression is currently being evaluated in the REPL thread. If not caught, this will cause the error to be raised at the console and a new prompt will be displayed. Issuing the signal twice will terminate &SISC;.

## Display Conventions

Executing or loading code in the REPL ordinarily produces a value result which is displayed during the Print phase. However, two other message types may be displayed. First, if an error is raised that is not handled by the running program, the message will be described in one of several forms, depending on what combinations of a location, a message, and a parent message the error has:

    Error.

    Error in <error-location>.

    Error: <description>

    Error in <error-location>: <description>

    Error in nested call.
    <nested-error>

    Error in nested call: <description>
    <nested-error>

    Error in nested call from <error-location>.
    <nested-error>

    Error in nested call from <error-location>: <description>
    <nested-error>

The location of an error often refers to the name of a procedure, syntax, or parameter. Errors that do not contain a location often originate in an anonymous function. Nested errors occur when one function makes a call to another function and the second raises an error. If the first function wishes, it may catch this error and generate its own, with the second functions error as a parent. Thus a nested error consists of an error message on the first line, and the nested error message or messages on following lines.

In addition to errors, it is possible for code to produce warnings during compilation or run-time. A warning is a message to the user about a condition that is unusual but not terminal to the program flow. The compiler, for example, does a minimal amount of sanity checking on code and may produce warnings about code that has the potential to raise errors during execution. Warnings are always distinguished from ordinary messages by surrounding braces ({}) and starting with the word 'warning'.

    {warning: <description>}

## Running &SISC;

&SISC;'s official distribution provides a startup script for Windows and Unix based hosts. Simply executing this script starts the &SISC; REPL. Zero or more Scheme source files can also be specified on the command line after the script name, which will be loaded in order before the REPL prompt is displayed.

It may be desirable to pass options to the underlying JVM. This can be done by setting the `JAVAOPT` environment variable to the options you wish to pass to the JVM. This includes switches for heap size, system properties, etc. &SISC; itself has a number of properties that can affect its operation. See config-parameters for a list of these properties and their meanings.

### Command-line Switches

&SISC; can, in addition to loading Scheme source programs, also accept a few command-line switches to change its behavior. Any non-switch argument is considered a Scheme source file to load on startup, until the end of options characters "--" are reached. Any item after those characters are considered arguments to the function specified in the "call-with-args" switch.

All command-line switches have both a short and long form. These forms are equivalent in meaning.

### &SISC; Command line Switches

Long Switch | Short Switch | Switch meaning
`--call-with-args <name>` | `-c <name>` | Call the top-level procedure `name` with the remaining command-line arguments after the "--" sequence.
`--eval <expression>` | `-e <expression>` | Evaluate the provided expression.
`--no-repl` | `-x` | Exit after loading all the Scheme source files and processing all command-line switches.
`--heap <heap-file>` | `-h <heap-file>` | File containing pre-compiled code and data for a complete Scheme top-level environment. This parameter is mandatory if the heap cannot be located automatically.
`--properties <config-file>` | `-p <config-file>` | Specifies a Java properties file that contains application properties. Typically some of these properties define defaults for configuration parameters (config-parameters. The file can be specified as a URL.
`--listen [<host>:]<port>` | `-l [<host>:]<port>` | Listen on host/port for REPL connections, i.e. connecting to the specified host/port will create a new REPL.

The order of processing the command line is as follows:

1. Process the entire command line, noting the settings of each switch and accumulating all Scheme source files and arguments after the end of options sequence.

2. Load the heap file.

3. Load each Scheme source file found in the order they occured on the command line. Note whether any errors occurred.

4. If present, evaluate the expression in an `--eval` switch. Note its success or failure.

5. If present, apply the named function in a `--call-with-args` switch to the arguments after the end of options sequence. Note its return value.

6. If `--no-repl` was not specified, invoke the REPL, otherwise exit.

7. If the REPL was run if its return value is an integer, return that integer as &SISC;'s overall return code. If the REPL was not run, and any return code supporting step above was run, return the most recent return code. If no return code step was performed, but a success/failure step was performed, return 1 if any failures occured, 0 otherwise.

### Configuration Parameters

SISC's behaviour is affected by a number of configuration parameters. These fall into two categories:

1. Static configuration parameters that can only be specified at system startup and apply across all &SISC; applications that use the same classloader.

2. Dynamic configuration parameters that can be altered on a per-thread basis without impacting other threads. These kind of parameters are also called "thread locals", or, in Scheme terminology, dynamic parameters.

#### Static Parameters

Static configuration parameters can be set using Java system properties. Their value can be retrieved with a Scheme function, but it is not possible to alter it. Static configuration parameters default to pre-defined system-internal settings if left unspecified.

&SISC; has the following static configuration parameters:

Java property The names of all properties for configuration parameters must be prefixed with `sisc.`. | Scheme parameter | default | description
`permitInterrupts` | `permit-interrupts` | true | If set to `true`, `thread/interrupt` is permitted to interrupt running Scheme code, in addition to sending an interrupt signal to the host language.
`minFloatPrecision` | `min-float-precision` | 16 | Specifies the minimum precision, in decimal places, to be maintained by the Quantity lib if using arbitrary precision floats.
`maxFloatPrecision` | `max-float-precision` | 32 | Specifies the maximum precision, in decimal places, to be maintained by the Quantity lib if using arbitrary precision floats.

When static configuration parameters are retrieved with their associated Scheme function, the value is of the type specified for the parameter. See config-parameter-conversion.

#### Dynamic Parameters

There are four ways to specify a configuration parameter, in decreasing order of precedence:

1. Invoking a scheme function. Dynamic configuration parameters are special Scheme parameters (see Parameters. Invoking the parameter with a value sets the parameter for the current thread without affecting other dynamic contexts / threads.

2. Defining an application property. A single &SISC; runtime can host multiple applications simultaneously. Application properties define default values for dynamic configuration parameters across all dynamic contexts / threads of an application. They can be specified at application initialisation time. See JavaToScheme. When &SISC; is started from the command line, the location of a Java properties file containing application properties can be specified with a command line option. See commandline-switches.

3. Defining a Java system property. Java system properties define default values for dynamic configuration parameters that apply across all applications inside a single &SISC; runtime.

4. System defaults. All dynamic configuration parameters have a reasonable default value.

&SISC; has the following dynamic configuration parameters:

Java property | Scheme parameter | default | description
`caseSensitive` | `case-sensitive` | false | Determines whether symbols read via the Scheme reader are to be treated case sensitively.
`characterSet` | `character-set` | "UTF8" | Defines the default character set used by character ports (see charports) if no character set is otherwise specified.
`emitAnnotations` | `emit-annotations` | true | If set to `true`, this parameter causes source files loaded with `load` or `import`, as well as source entered in the console, to be annotated by the Scheme reader. Annotations include source file location information, which simplifies debugging. See passive-debugging.
`emitDebuggingSymbols` | `emit-debugging-symbols` | true | If set to `true`, additional annotations useful for debugging, such as function and variable names, are produced by &SISC;'s compiler. See passive-debugging.
`maxStackTraceDepth` | `max-stack-trace-depth` | 0 | Specifies the maximum depth of virtual call stacks, which are used to obtain proper stack traces even in the presence of tail recursion and continuation capture and invocation, while still preserving tail-call semantics and safe-for-space guarantees. See Debugging. Collecting this information is computationally expensive, so this feature is turned off by default. A value of `16` is about right for debugging most applications. Large values allow collection of more information but carry a large performance penalty, small values result in some call information being lost.
`permissiveParsing` | `permissive-parsing` | false | If set to `true`, the Scheme parser will warn rather than raise an error for various syntactic errors such as unbalanced parentheses. This allows one to continue parsing a syntactically invalid file, finding many errors at once.
`printShared` | `print-shared` | true | If set to `true`, `write` and the REPL detect shared structures in data and invoke a version of `write` capable of emitting the shared structure's external representation of data. See Writing. The user may wish to set this parameter to `false` because of the overhead of both scanning all data, and constructing this representation when shared structures are detected.
`replPrompt` | `repl-prompt` |  | String to be displayed as part of &SISC;'s REPL prompt.
`stackTraceOnError` | `stack-trace-on-error` | true | If set to `true`, whenever an uncaught error is encountered a full stack trace is displayed automatically. See passive-debugging.
`strictR5RSCompliance` | `strict-r5rs-compliance` | false | If set to `true`, strict &R5RS; syntax and semantics are followed. This will cause SISC to raise errors in all situations described as "an error" in the Scheme standard. This will override and invalidate all the interpretation liberties described in R5RSViolations.
`synopsisLength` | `synopsis-length` | 30 | Limit on the length (in characters) of the external representation of data structures in error messages and warnings. When the limit is reached, an ellipsis (`...`) is appended to the curtailed external representation.
`vectorLengthPrefixing` | `vector-length-prefixing` | true | If set to `true`, this parameter will instruct the pretty-printer to emit length prefixed, trailing-duplicate-eliminated vectors in its output. If `false`, ordinary full-length vectors without prefixes will be emitted. See Vectors.

When dynamic configuration parameters are retrieved or set with their associated Scheme function, the value is of the type specified for the parameter. See config-parameter-conversion.

#### Value Conversion

When specifying configuration parameters via Java properties, a Java-like notation is used, e.g. boolean parameters are specified as `true` and `false`. By contrast, when getting and setting configuration parameters from Scheme, their values are of the appropriate Scheme type, e.g. boolean parameters are specified as `#t` and `#f`. Strings and symbols undergo a similiar conversion; they are specified without their double/single quotes in the Java properties.

For parameter types other than boolean, string and symbol, Java properties are read as Scheme values, i.e. Scheme literal notation should be used in the properties.

## Running Scheme Programs

### Loading

&SISC; supports loading Scheme programs using the &R5RS; optional procedure `load`. A number of file types for loading Scheme code are supported. The common extensions are:

- `scm` - Scheme source code

- `sce` - Scheme code expanded. This type of code has been processed by the syntax expander and contains only core Scheme forms.

- `scc` - &SISC; Compiled Code. This contains expanded and compiled code in a &SISC; specific representation. The code gets executed when loaded.

In addition to code loaded, &SISC; requires a heap, which contains the default set of libraries and functions for the initial environment. &SISC; will look for a heap file called `sisc.shp` in the current directory, the directory referenced by the `SISC_HOME` environment variable, and as a resource paired with the `HeapAnchor` class in the `sisc.boot` package of the classpath. The standard &SISC; distribution contains `sisc.shp` in the same directory as the supporting `.jar` files.

It isn't uncommon to want the heap to reside on the classpath, where it can be more easily resolved in applets or in web applications. This file, usually called `sisc-heap.jar` can be added to the classpath in any usual fashion, and the heap loading routines will discover it if not found elsewhere. To create a jar file containing the heap, create the following file structure in the jar:

    sisc/
    sisc/boot/
    sisc/boot/HeapAnchor.class
    sisc/boot/sisc.shp

The `HeapAnchor.class` class file is distributed in the `sisc-opt.jar` file of the full binary distribution.

### Scheme Shell Scripts

On Unix or Unix-like systems, &SISC; supports SRFI-22, a mechanism for writing shell-like scripts that can be invoked directly as executable programs. The text of the SRFI, which can be found at http://srfi.schemers.org, describes how such programs are written.