Go to the first, previous, next, last section, table of contents.


How to start up and run Kawa

The easiest way to start up Kawa is to run the `kawa' program. This finds your java interpreter, and sets up `CLASSPATH' correctly. If you have installed Kawa such $PREFIX/bin is in your $PATH, just do:

kawa

However, `kawa' only works if you have a Unix-like environment. On some platforms, `kawa' is a program that uses the GNU `readline' library to provide input line editing.

To run Kawa manually, you must start a Java interpreter. How you do this depends on the Java interpreter. For JavaSoft's JDK, you must have the Java interpreter in your PATH. You must also make sure that the kawa/repl.class file, the rest of the Kawa packages, and the standard Java packages can be found by searching CLASSPATH. See section Getting and running Java.

Then you do:

java kawa.repl

In either case, you will then get the `#|kawa:1|#' prompt, which means you are in the Kawa read-eval-print-loop. If you type a Scheme expression, Kawa will evaluate it. Kawa will then print the result (if there is a non-"void" result).

Command-line arguments

You can pass various flags to Kawa, for example:

kawa -e '(display (+ 12 4))(newline)'

or:

java kawa.repl -e '(display (+ 12 4))(newline)'

Either causes Kawa to print `16', and then exit.

At startup, Kawa executes an init file from the user's home directory. The init file is named .kawarc.scm on Unix-like systems (those for which the file separator is '/'), and kawarc.scm on other systems. This is done before the read-eval-print loop or before the first -f or -c argument. (It is not run for a -e command, to allow you to set options to override the defaults.)

`-e expr'
Kawa evaluates expr, which contains one or more Scheme expressions. Does not cause the ~/.kawarc.scm init file to be run.
`-c expr'
Same as `-e expr', except that it does cause the ~/.kawarc.scm init file to be run.
`-f filename'
Kawa reads and evaluates expressions from the file named by filename. If filename is `-', standard input is read (with no prompting).
`-s'
`--'
The global variable `command-line-arguments' is set to the remaining arguments (if any), and an interactive read-eval-print loop is started. This uses the same "console" as where you started up Kawa; use `-w' to get a new window.
`-w'
Creates a new top-level window, and runs an interactive read-eval-print in the new window. See section Running a Command Interpreter in a new Window. Same as -e (scheme-window #t). You can specify multiple `-w' options, and also use `-s'.
`--version'
Prints out the Kawa version number, and then exits.
`--server portnum'
Start a server listening from connections on the specified portnum. Each connection using the Telnet protocol causes a new read-eval-print-loop to started. This option allows you to connect using any Telnet client program to a remote "Kawa server".
`--scheme'
Set the default language to Scheme. (This is the default unless you select another language.)
`--elisp'
Set the default language to Emacs Lisp. (This is not very useful yet - little beyond the parser works.)

The following options control which calling conventions are used:

`--full-tailcalls'
Use a calling convention that supports proper tail recursion.
`--no-full-tailcalls'
Use a calling convention that does not support proper tail recursion. Self-tail-recursion (i.e. a recursive call to the current function) is still implemented correctly, assuming that the called function is known at compile time.

The default is currently --no-full-tailcalls because I believe it is faster (though I have not done any measurements yet). It is also closer to the Java call model, so may be better for people primarily interested in using Kawa for scripting Java systems.

Both calling conventions can co-exist: Code compiled with --full-tailcalls can call code compiled with --no-full-tailcalls and vice versa.

The options `-C', `-d', `-T', `-P', and `--main' are used to compile a Scheme file; see section Compiling Scheme to a set of .class files. The option `--connect portnum' is only used by the `kawa' front-end program.

If there are further command-line arguments after the options have been processed, then the first remaining argument names a file that is read and evaluated. If there is no such argument, then Kawa enters an interactive read-eval-print loop, but only if none of the `-c', `-e', `-f', `-s', `-C', or `--' options were specified.

Running a Command Interpreter in a new Window

An alternative interface runs the Java read-eval-print-loop inside a new window. This is in some ways nicer. One reason is that it provides better editing. You can also create new windows. They can either have different top-level environments or they can share environments. To try it, do:

java kawa.repl -w

Exiting Kawa

Kawa normally keeps running as long as there is an active read-eval-print loop still awaiting input or there is an unfinished other computation (such as requested by a `-e' of `-f' option).

To close a read-eval-print-loop, you can type the special literal #!eof at top level. This is recognized as end-of-file. Unfortunately, due to thread-related complications, just typing an end-of-file character (normally ctrl/D until Unix), will not work.

If the read-eval-print-loop is in a new window, you can select `Close' from the `File' menu.

To exit the entire Kawa session, call the exit procedure (with 0 or 1 integer arguments).


Go to the first, previous, next, last section, table of contents.