The binary release comes as a .zip archive that includes Kawa itself (as a .jar file kawa-version.jar), some third-party helper libraries, kawa command scripts (for GNU/Linux/Unix/MacOS or Windows), and documentation (basically this manual).

After downloading (see Getting Kawa), extract the files from the .zip archive using a suitable unzip program, which will create a directory kawa-version, with lib, bin, and doc sub-directories. In the following, we assume the environment variable KAWA_HOME refers to this directory:

unzip ~/Downloads/kawa-version.zip
export KAWA_HOME=`pwd`/kawa-version

The binary release requires Java 8 or later. If you have an older Java implementation, or build for a mobile environment like Android, then you will need to get the source distribution.

If you want to use Kawa as part of some other application, you just need the $KAWA_HOME/lib/kawa.jar.

Running the kawa command

To run a Kawa script file or the Kawa read-eval-print-loop run the Kawa application. There are various way to do so.

The recommended way is to execute the $KAWA_HOME/bin/kawa Bash shell script. This should work on most Unix-like platforms that have Bash installed, including GNU/Linux, BSD, MacOS, and Cygwin/MingW. (Please report if you have problems.)

The script assumes that either a suitable java program is in your PATH; or the JAVA environment variable names a suitable java executable; or that JAVA_HOME is set so $JAVA_HOME/bin/java is suitable.

If you want to put kawa in your search path you can of course do:

PATH=$KAWA_HOME/bin:$PATH

Alternatively you can create a symbolic link in an already-searched directory. For example:

cd /usr/local/bin
ln -s $KAWA_HOME/bin/kawa kawa

The bin/kawa.bat script works on Windows.

Both scripts add some helper libraries, including support for input editing.

It is also possible to run Kawa using java directly:

java -jar $KAWA_HOME/lib/kawa.jar

or:

CLASSPATH=$KAWA_HOME/lib/kawa.jar
export CLASSPATH
java kawa.repl

On Windows:

set classpath=%KAWA_HOME%\lib\kawa.jar

To run Kawa in a fresh window use the -w flag:

kawa -w

or

java kawa.repl -w

Reading the documentation

The file doc/kawa-manual.epub contains the Kawa documention packaged as an electronic book, which is readable by most e-book readers. Plugins are also available for common browsers, for example EPUBReader for firefox.

Even easier is to invoke bin/kawa --browse-manual (or on Windows: bin\kawa.bat --browse-manual).

An epub is essentially a zip archive, which you can unzip:

cd $KAWA_HOME/doc
unzip kawa-manual.epub

Then you can use a plain browser with the URL file:$KAWA_HOME/doc/OEBPS/index.html.