## Installing and using the source distribution

The Kawa release normally comes as a gzip-compressed tar file named ‘`kawa-2.92_invoke.tar.gz`’. Two methods are supporting for compiling the Kawa sources; choose whichever is most convenient for you.

One method uses the traditional GNU `configure` script, followed by running `make`. This works well on Unix-like systems, such as GNU/Linux. You can also use this method on Microsoft Windows, with the help of tools from MinGW or Cygwin.

The other method uses the `ant` command, a Java-based build system released by Apache’s Jakarta project. This uses an `build.xml` file in place of `Makefile`s, and works on non-Unix systems such as Microsoft Windows. However, the `ant` method does not support all the features of the `configure`+`make` method.

### Build Kawa using `configure` and `make`

(See below for some notes for building on Microsoft Windows.)

If you have a `tar.gz` file, first unpack that in your build directory:

    tar xzf kawa-2.92_invoke.tar.gz
    cd kawa-2.92_invoke

If you’re building from the Git repository, you need to generate `configure` and some other files. This is easiest done with the `autogen.sh` script:

    ./autogen.sh

Then you must configure the sources. This you do in the same way you configure most other GNU software. Normally you can just run the configure script with no arguments:

    ./configure

The `configure` script takes a number of options.

If you have installed Kawa before, make sure your `CLASSPATH` does not include old versions of Kawa, or other classes that may conflict with the new ones.

Then you need to compile all the .java source files. Just run make:

    make

This assumes that ‘`java`’ and ‘`javac`’ are the java interpreter and compiler, respectively.

It has been reported that parallel make doesn’t work, so don’t use the `-j2` or above options.

You can now test the system by running Kawa in place:

    java kawa.repl

or you can run the test suite:

    make check

or you can install the compiled files:

    make install

This will install your classes into `$PREFIX/share/java` (and its sub-directories). Here `$PREFIX` is the directory you specified to configure with the `--prefix` option, or `/usr/local` if you did not specify a `--prefix` option.

To use the installed files, you need to set `CLASSPATH` so that `$PREFIX/share/java/kawa.jar` is in the path:

    CLASSPATH=$PREFIX/share/java/kawa.jar
    export CLASSPATH

This is done automatically if you use the ‘`kawa`’ script.

#### Configure options

The `configure` script takes a number of options. The `--help` switch gives you a list of options. The following are some of the more common or important ones.

`--prefix=`install-dir``
`--prefix `install-dir``

  By default `make install` will install the compiled `.jar` files info `/usr/local/share/java`, the `kawa` command into `/usr/local/bin`, and so on in `/usr/local`. The `--prefix` option causes the files to be installed under ``install-dir`` instead of `/usr/local`. For example to install the `.jar` in `/opt/kawa/share/java` and otherwise use `/opt/kawa` do:

      ./configure --prefix=/opt/kawa

`--with-java-source=`version``

  As distributed, the Kawa source code requires Java 7. If you only have Java 6 or Java 5, use the `--with-java-source` option:

      ./configure --with-java-source=5

  Kawa no longer supports older verisons of Java (JDK 1.4 or older). It might be possible to use a tool like Retroweaver on the Kawa `.jar` to fix up Java 5 dependencies. Contact the Kawa author if you want to be a tester for this.

`--with-docbook-stylesheet[=`path`]`

  Build the documentation (this manual) as an electronic book (in ebook format) or a website, using the DocBook xslt stylesheets. (You can build the documentation without DocBook, but using it enables nicer-looking and more functional documentation.)

  The stylesheets are found using `path`; the file ``path`/epub3/chunk.xsl` needs to exist. (For example, on Fedora 25 `path` can be `/usr/share/sgml/docbook/xsl-ns-stylesheets`.)

`--with-domterm`
`--with-domterm=`domterm_home``

  Compile with extra support for the DomTerm terminal emulator library, where ``domterm_home`` is such that ``domterm_home`/lib/domterm.jar` exists. (Some DomTerm support is built-in regardless.)

  If you use this option along with `--with-javafx` then creating a new REPL window will create a DomTerm window.

  As an optional convenience, you can use the `domterm.jar` in the Kawa binary distribution.

`--with-jline3`
`--with-jline3=`jline3.jar``

  Build support for using JLine 3, which is a library for handling console input, similar to GNU readline. If specified, the `jline3.jar` is added to the classpath of the generated `kawa.sh` or `kawa` shell program.

  An advantage of `--with-jline3` (compared to `--enable-kawa-frontend`) is that the former works without native code (on most Unix-like platforms), and it does not require a C wrapper program.

  As an optional convenience, you can use the `jline.jar` in the Kawa binary distribution.

`--with-domterm`
`--with-domterm=`domterm.jar``

  Compile with extra support for the DomTerm terminal emulator library. (Some DomTerm support is built-in regardless.)

  If you use this option along with `--with-javafx` then creating a new REPL window will create a DomTerm window.

  As an optional convenience, you can use the `domterm.jar` in the Kawa binary distribution.

`--with-jline3`
`--with-jline3=`jline3.jar``

  Build support for using JLine 3, which is a library for handling console input, similar to GNU readline. If specified, the `jline3.jar` is added to the classpath of the generated `kawa.sh` or `kawa` shell program.

  An advantage of `--with-jline3` (compared to `--enable-kawa-frontend`) is that the former works without native code (on most Unix-like platforms), and it does not require a C wrapper program.

  As an optional convenience, you can use the `jline.jar` in the Kawa binary distribution.

`--with-servlet`
`--with-servlet=`servlet-jar``

  Build support for servlets, which are used in web servers. This requires the `servlet-api.jar` (available various places including Tomcat or Glassfish), for `javax.servlet.Servlet` and related classes. If this class isn’t in your classpath, specify its location as ``servlet-jar``. For example:

      ./configure --with-servlet=/path/to/servlet-api.jar

`--enable-jemacs`

  Build JEmacs (enable Emacs-like text editor) and support (a subset of) the Emacs Lisp language. JEmacs is a proof of concept - not really usable or maintained.

`--with-javafx`
`--with-javafx=`javafx-jar``
`--with-javafx=`java-home``

  Set this flag to enable the convenience features for JavaFX. The JavaFX classes are included in JDK 8 (but not OpenJDK 8), and you don’t need to specify ``javafx-jar`` or ``java-home``. For JDK 7 you need to specify ``javafx-jar`` (the path to `javafx.rt`) or ``java-home`` (the value of the `$JAVA_HOME`).

`--with-android=`android-jar``

  Build for the Android platform. This requires special instructons.

`--enable-kawa-frontend`

  If you have the GNU ‘`readline`’ library installed, you might try adding the ‘`--enable-kawa-frontend`’ flag. This will build the ‘`kawa`’ front-end program, which provides input-line editing and an input history. You can get ‘`readline`’ from archives of GNU programs, including ftp://www.gnu.org/.

  Note that using JLine, enabled by `--with-jline3`, is now recommended instead of using the `readline` frontend.

  You may need to specify to `make` where to find the `readline` include files (with `READLINE_INCLUDE_PATH`) and the library (with `READINE_LIB_PATH`). For example on OS/X you need to do:

      make READLINE_INCLUDE_PATH=-I/usr/local/unix/readline/include \
           READLINE_LIB_PATH=-L/usr/local/unix/readline/lib

#### Building on Windows using MinGW

The Kawa `configure` and `make` process assumes Unix-like tools, which you can get from the MinGW project. Download the MingGW Installation Manager, and use it to install at least `mingw-developer-toolkit`. (Also installing `msys-groff` avoids a minor problem building the documentation.)

The `C:\MinGW\msys\1.0\msys.bat` script creates a command window with the `bash` shell and the `PATH` set up as needed. Alternatively, you can use the standard Windows command prompt if you set your `PATH` as described in here.

#### Building on Windows using Cygwin

The free Cygwin environment can be used for building Kawa: The Kawa configure script recognizes Cygwin, and modifies the classpath to use Windows-style path separators.

Beyond the base packages, you probably want to install `autoconf`, `automake`, `git`, `texinfo`, `groff`, `make`, and `diffutils`.

Cygwin (unlike MinGW) has a current version of `makeinfo`, but an undiagnosed bug still prevents building `kawa.info`. You can work around that problem with `touch doc/kawa.info`.

### Building the documentation

To build the documentation in a form suitable for a web-site do:

    cd doc && make web/index.html

You can then point your browser at `file:/`kawa_srcdir`/doc/web/index.html`.

The above requires `makeinfo` from the texinfo package, and the DocBook XSLT tools.

If you don’t have the DocBook XSLT tools (but have `makeinfo`), you can build a more plain HTML version of the documentation:

    cd doc && make kawa-html/index.html

In this case, point your browser at `file:/`kawa_srcdir`/doc/kawa-html/index.html`.

To build an `EPUB` file suitable for ebook readers, as well as enabling support for the `kawa --browse-manual` option, do:

    cd doc && make kawa-manual.epub

To build a `pdf` file suitable for printing or online viewing do:

    cd doc && make kawa.pdf

The resulting `kawa.pdf` is somewhat unsatisfactory - when viewed online, links aren’t clickable. Furthermore, box drawing characters are missing.

### Build Kawa using `ant`

Kawa now includes an Ant buildfile (`build.xml`). Ant is a part of the Apache Jakarta project. If you don’t hava Ant installed, get it from http://ant.apache.org/bindownload.cgi. The build is entirely Java based and works equally well on *nix, Windows, and presumably most any other operating system.

Once Ant has been installed and configured (you may need to set the `JAVA_HOME`, and `ANT_HOME` environment variables), you should be able to change to the directory containing the `build.xml` file, and invoke the ‘`ant`’ command. With the default settings, a successful build will result in a `kawa-2.92_invoke.jar` in the current directory.

There are a few Ant "targets" of interest (they can be supplied on the Ant command line):

`all`

  This is the default, it does `classes` and `jar`.

`classes`

  Compiles all the files into `*.class` files into the directory specified by the `build.dir` property.

`jar`

  Builds a jar into into the directory specified by the `dist.dir` property.

`runw`

  Run Kawa in a GUI window.

`clean`

  Deletes all files generated by the build, including the jar.

There is not yet a `test` target for running the testsuite.

There are various “properties" that control what `ant` does. You can override these on the command line or by editing the `build.properties` file in the same directory as `build.xml`. For example, the `build.dir` property tells `ant` where to build temporary files, and where to leave the resulting `.jar` file. For example, to leave the generated files in the sub-directory named `BUILD` do:

    ant -Dbuild.dir=BUILD

A sample `build.properties` is provided and it contains comments explaining many of the options.

Here are a few general properties that help to customize your build:

`build.dir`

  Path to put the temporary files used for building.

`dist.dir`

  Path to put the resulting jar file.

`version.local`

  A suffix to add to the version label for your customized version.

`debug`

  Whether (true/false) the Javac "-g" option is enabled.

`optimize`

  Whether (true/false) the Javac "-O" option is enabled.

Here are some Kawa-specific ones (all `true`/`false`): `with-collections`, `with-references`, `with-awt`, `with-swing`, `enable-jemacs`, and `enable-servlet`> See the sample `build.properties` for more information on these.

If you change any of the build properties, you will generally want to do an ‘`ant clean`’ before building again as the build is often not able to notice that kind of change. In the case of changing a directory path, you would want to do the `clean` before changing the path.

A special note for NetBeans users: For some reason the build-tools target which compiles an Ant task won’t compile with the classpath provided by NetBeans. You may do ‘`ant build-tools`’ from the command line outside of NetBeans, in which case you will not want to use the `clean` target as that will delete the tool files as well. You can use the `clean-build` and/or `clean-dist` targets as appropriate. Alternatively you can add `ant.jar` to the `build-tools` classpath by copying or linking it into a `lib/ext` directory in Kawa’s source directory (the one containing the `build.xml` file).