An option can be followed by a value, as in --warn-invoke-unknown-method=no. For boolean options, the values yes, true, on, or 1 enable the option, while no, false, off, or 0 disable it. You can also negate an option by prefixing it with no-: The option --no-warn-unknown-member is the same as --warn-unknown-member=no.

These options can also be used in the module source, using module-compile-options or with-compile-options. (In that case they override the options on the command line.)

These options are processed when invoking the kawa application (i.e. the kawa.repl application). If you want a Kawa application compiled with --main to process these these assignments, call the process-command-line-assignments utility function.

The following options control which calling conventions are used:

The default is currently --no-full-tailcalls because it is usually faster. 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.

These options can also be used in the module source, using module-compile-options or with-compile-options. (In that case they override the options on the command line.)

The options ‘-C’, ‘-d’, ‘-T’, ‘-P’, ‘--main’ ‘--applet’, and --servlet are used to compile a Scheme file; see the section called “Compiling to a set of .class files”. The options ‘--module-static’, --module-nonstatic, --no-module-static, and --module-static-run control how a module is mapped to a Java class; see the section called “How a module becomes a class”. The option ‘--connect portnum’ is only used by the ‘kawa’ front-end program.

The following options are useful if you want to debug or understand how Kawa works.

JDK 6 (or later) includes a complete web server library.

The kawa front-end can pass options to the java launcher, using -J or -D options. These must be given before any other arguments. For example:

kawa -J-Xms48m -Dkawa.command.name=foo foo.scm --

is equivalent to (ignoring classpath issues):

java -Xms48m -Dkawa.command.name=foo kawa.repl foo.scm --

If you need to specify extra arguments to kawa, you can run arbitrary shell command inside Scheme block comments. Here is an example:

#!/bin/sh
#|
exec kawa out:base=16 out:radix=yes "$0" "$*"
|#
(format #t "The command-line is:~{ ~w~}.~%" (command-line))
(display "It has ")
(display (apply + (map string-length (command-line))))
(display " characters.")
(newline)

The trick is to hide the shell code from Kawa inside a #|...|# block-comment. The start of the block comment is a line starting with a #, so it is treated as a comment by the shell. You can then invoke kawa (or java directly) as you prefer, setting up class-path and jars as needed, and passing whatever arguments you want. (The shell replaces the "$0" by the name the script, and replaces the "$@" by the remaining arguments passed to the script.) You need to make sure the shell finishes before it reaches the end of the block comment or the Scheme code, which would confuse it. The example uses exec, which tells the shell to replace itself by kawa; an alternative is to use the shell exit command.

If you copy the above file to /tmp/sch-echo and make that file executate, you can run it directly:

$ /tmp/scm-echo "a b" "c d"
The command-line is: "/tmp/scm-echo" "a b c d".
It has #x14 characters.

When the Kawa reader sees the initial #/ it sets the command name to the file name, so it can be used by a future call to (command-name). If you want to override this you can use the -Dkawa.command.name=name option.

Using comments this way has the advantage that you have the option of running the script “manually” if you prefer:

$ kawa /tmp/scm-echo out:base=8 "x y"
The command-line is: "/tmp/scm-echo" "out:base=8" "x y".
It has 26 characters.

An argument consisting of just a \ (backslash) causes Kawa to read the second line looking for options. (Quotes and backslahes work like in the shell.) These replace the backslash in the command line.

This is a less verbose mechanism, but it requires an absolute path to kawa, due to shell limitations.

#!/usr/bin/bin/kawa \
  --scheme --full-tailcalls
(format #t "The command-line is:~{ ~w~}.~%" (command-line))

In this case the efective command line received by Kawa will be --scheme, --full-tailcalls, followed by the script filename, followed by other arguments specified when running the script.

The backslash used this way originated in scsh where it is called the meta-arg. (Unlike scsh, Kawa's #! is not a block comment, but a rest-of-line, though the backslash causes the following line to also be skipped.)

An alternative method is to use the --script2 option, which tells Kawa to execute the script after ignoring the initial two lines. For example:

#!/bin/sh
exec kawa --commonlisp out:base=16 --script2 "$0" "$@"
(setq xx 20) (display xx) (newline)

This slightly more compact than using block-comments as shown earlier, but it has the disadvantage that you can't explicitly use kawa or java to run the script unless you make sure to pass it the --script2 option.

If you compile your Kawa application to class files (or better: a jar file), you probably still want to write a small shell script to set things up. Here is one method:

#!/bin/sh
export CLASSPATH=/my/path
exec kawa -Dkawa.command.name="$0" foo "$@"

Using the kawa front-end is a convenience, since it automatically sets up the paths for the Kawa classes, and (if enabled) if provides readline support for the default input port.

Setting the kawa.command.name property to "$0" (the filename used to invoke the script) enables (command-line) to use the script name as the command name.

You can invoke java directly, which is necessary when running a jar file:

#!/bin/sh
exec java -cp /path/to/kawa -Dkawa.command.name="$0" foo.jar "$@"

(It is in principle possible to compile a Kawa application to “a native executable”, for example using gcj. However, this is no longer supported, as gcj is no longer being actively developed.)

Invoking ‘kawa’ (or ‘java kawa.repl’) with the ‘-C’ flag will compile a ‘.scm’ source file into one or more ‘.class’ files:

kawa --main -C myprog.scm

You run it as follows:

kawa [-d outdirectory] [-P prefix] [-T topname] [--main | --applet | --servlet] -C infile ...

Note the ‘-C’ must come last, because ‘Kawa’ processes the arguments and options in order,

Here:

When you actually want to load the classes, the outdirectory must be in your ‘CLASSPATH’. You can use the require syntax or the load function to load the code, by specifying the top-level class, either as a file name (relative to outdirectory) or a class name. E.g. if you did:

kawa -d /usr/local/share/java -P my.lib. -T foo -C foosrc.scm

you can use either:

(require my.lib.foo)

or:

(load "my.lib.foo")

Using require is preferred as it imports the definitions from my.lib.foo into the compile-time environment, while load only imports the definitions into run-time environment.

If you are compiling a Scheme source file (say ‘foosrc.scm’) that uses macros defined in some other file (say ‘macs.scm’), you need to make sure the definitions are visible to the compiler. One way to do that is with the ‘-f’:

kawa -f macs.scm -C foosrc.scm

Many of the options described earlier are relevant when compiling. Commonly used options include language selection, the --warn-xxx options, and --full-tailcalls.

Many Java projects use Ant for building Java projects. Kawa includes a <kawac> Ant ask that simplifies compiling Kawa sources files to classes. See the build.xml in the Kawa source distribution for examples. See the kawac task documentation for details.

A Java application is a Java class with a special method (whose name is main). The application can be invoked directly by naming it in the Java command. If you want to generate an application from a Scheme program, create a Scheme source file with the definitions you need, plus the top-level actions that you want the application to execute.

For example, assuming your Scheme file is MyProgram.scm, you have two ways at your disposal to compile this Scheme program to a standalone application:

Both method will create a MyProgram.class which you can either load (as decribed in the previous section), or invoke as an application:

java MyProgram [args]

Your Scheme program can access the command-line arguments args by using the global variable ‘command-line-arguments’, or the R6RS function ‘command-line’.

If there is no explicit module-export in a module compiled with --main then no names are exported. (The default otherwise is for all names to be exported.)

An applet is a Java class that inherits from java.applet.Applet. The applet can be downloaded and run in a Java-capable web-browser. To generate an applet from a Scheme program, write the Scheme program with appropriate definitions of the functions ‘init’, ‘start’, ‘stop’ and ‘destroy’. You must declare these as zero-argument functions with a <void> return-type.

Here is an example, based on the scribble applet in Flanagan's "Java Examples in a Nutshell" (O'Reilly, 1997):

(define-private last-x 0)
(define-private last-y 0)

(define (init) :: void
  (let ((applet (this)))
    (applet:addMouseListener
     (object (java.awt.event.MouseAdapter)
	     ((mousePressed e)
	      (set! last-x (e:getX))
	      (set! last-y (e:getY)))))
    (applet:addMouseMotionListener
     (object (java.awt.event.MouseMotionAdapter)
	     ((mouseDragged e)
	      (let ((g (applet:getGraphics))
		    (x (e:getX))
		    (y (e:getY)))
		(g:drawLine last-x last-y x y)
		(set! last-x x)
		(set! last-y y)))))))

(define (start) :: void (format #t "called start.~%~!"))
(define (stop) :: void (format #t "called stop.~%~!"))
(define (destroy) :: void (format #t "called destroy.~%~!"))

You compile the program with the ‘--applet’ flag in addition to the normal ‘-C’ flag:

java kawa.repl --applet -C scribble.scm

You can then create a ‘.jar’ archive containing your applet:

jar cf scribble.jar scribble*.class

Finally, you create an ‘.html’ page referencing your applet and its support jars:

<html><head><title>Scribble testapp</title></head>
<body><h1>Scribble testapp</h1>
You can scribble here:
<br>
<applet code="scribble.class" archive="scribble.jar, kawa-1.14.1.jar" width=200 height=200>
Sorry, Java is needed.</applet>
</body></html>

The problem with using Kawa to write applets is that the Kawa .jar file is quite big, and may take a while to download over a network connection. Some possible solutions:

Using GCJ with Kawa is no longer supported, as GCJ is no longer being actively maintained.

You can compile your Scheme program to native code using GCJ, as long as you have built Kawa using GCJ.

First, you need to compile the Scheme code to a set of .class files; see the section called “Compiling to a set of .class files”.

kawa --main -C myprog.scm

Then to create an executable myprog do:

gckawa --main=myprog myprog*.class -o myprog

The gckawa is a simple shell script that calls gcj. The reason for the wildcard in myprog*.class is that sometimes Kawa will generate some helper classes in addition to myprog.class. The --main option tell gcj which class contains the main method it should use. The -o option names the resulting executable program. The -lkawa option tells the linker it should link with the kawa shared library, and the -L$PREFIX/bin option tells the linker where it can find that library.