Source distribution (The Kawa Scheme language)

Installing and using the source distribution

The Kawa release normally comes as a gzip-compressed tar file named ‘kawa-3.1.1.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 Makefiles, 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
Building the documentation
Build Kawa using ant

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-3.1.1.tar.gz
cd kawa-3.1.1

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
Building on Windows using MinGW
Building on Windows using Cygwin

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 8. If you only have Java 7, Java 6, or Java 5, use the --with-java-source option:

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

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-stylesheets[=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, while on Debian use /usr/share/xml/docbook/stylesheet/docbook-xsl-ns.)

--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-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-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-home. JDK 11 or later does not include JavaFX, so you need to specify the location of the modular OpenJFX SDK as javafx-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

Plain HTML documentation
Fancier HTML documentation
Using ebook readers or the –browse-manual option
Building a printable PDF file

Plain HTML documentation

You can build a plain HTML version of the documentation (using makeinfo from the texinfo distribution):

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

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

Fancier HTML documentation

To build the documentation in a nicer form suitable for a web-site you need makeinfo and the DocBook XSLT tools (and to have run configure with the --with-docbook-stylesheets option):

cd doc && make web/index.html

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

Using ebook readers or the –browse-manual option

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

This also requires the DocBook XSLT tools.

Building a printable PDF file

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-3.1.1.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).