Porting Hints

Toba was designed with portability in mind. The current release supports Irix, Linux, and Solaris, although only the Linux implementation has just-in-time compiler support. Ports to other Unix systems should be fairly straightforward.

System Requirements

C Environment

Toba requires an ANSI C platform with the following features:

an ASCII or extended ASCII character set, such as ISO-8859
char, short, and int datatypes of 8, 16, and 32 bits, respectively
a 64-bit integral datatype, either long or long long
integer division and remainder operations matching the Java specification
IEEE-754 floating-point representations and behavior
linker support for 31 case-sensitive significant characters in external identifiers
a threads package

JDK

Toba requires version 1.1 of the Java Developers Kit on the host platform. Cross-building to a different target platform is not supported. The provided version of Toba is intended for use with JDK 1.1.6 or 1.1.7, although with an additional configuration option it will support 1.1.3. Version 1.1.5 is specifically not supported. It is likely that, if you use some other version, you will have to change either a native function implementation in the runtime source directory, or the patterns of classes linked into the API packages. See the detailed build notes for more information.

Garbage Collector

Toba uses the Boehm-Demers conservative garbage collector. This package has been widely ported and should build on most popular Unix boxes. If the garbage collector has not been ported to your machine it will have to be ported before you can build Toba. See the garbage collector's home page for more information. If you wish to use Toba without a garbage collector or with a different garbage collector you will have to edit runtime/alloc.c, runtime/lang_Runtime.c, runtime/monitor.c and runtime/runtime.c, possibly among others.

AWT

Toba uses the BISS AWT package to provide AWT support. For JDK 1.1, Toba uses the relatively unheralded and unsupported version 0.94 of BISS-AWT, available at the Java Linux archives (see the supporting sources list). This package uses the X windowing system to display graphics. If X is not available, the BISS AWT will have to be ported to the underlying graphics system. The BISS AWT also requires thread support. See the BISS home page for more information.

Configuration

Porting the Toba code itself involves setting up the make process, writing a threads interface and adjusting the code for any compile problems during the build.

Makefile

The build process is specified in the top-level Makefile, with platform-specific files in the ./configs directory, and the Makefiles in the sub-directories. The definitions used to parameterize the build process are described in ./configs/basic.mk, where the default values are set. Each Makefile includes this file, as well as ./configs/current.mk, which is used to override the default definitions with platform-specific settings. The configure script aggregates user options and builds a current.mk file based on them. To build for a new target, we suggest starting with an example current.mk and changing that to support your platform.

Driver Script

While building, Toba generates a shell-script driver program called bin/toba. This file is generated with flags from the top-level Makefile and with the bin/toba.sh file. If you need to make changes to the driver script you should edit the bin/toba.sh file and not the generated bin/toba file.

Threads Interface

There is a level of abstraction between the runtime system and the underlying threads package. This isolates the changes that need to be made to port to another threads package to two files. Each thread interface must provide a source file and a header file. These files are named runtime/sthreads_thrpack.c and runtime/sthreads_thrpack.h where thrpack is the name of a thread interface. During the build a link is made from sthreads.c and sthreads.h to one set of these files. Interface support for several existing thread packages are provided in ./configs/thread.thrpack.opt.

The underlying thread package that is used MUST be supported by the garbage collector. The garbage collector may require that certain flags be defined when compiling the collector and the threads interface package; set these in the GCCFLAGS Makefile variable. The C compiler may also require that certain flags be set when including C header files. These flags should be added to the CBUILD variable.

Previously Supported Platforms

WIN32 (NT and Windows/95/98) has not been supported for some time, due to a lack of expertise and need among Toba's developers. If you are able to get the system to work under WIN32, please send us patches.

Feedback

If you succeed in porting Toba to a new platform, please send the information back to the Sumatra project so that we can consider it for inclusion in future releases. We ask that you follow a few guidelines in any changes you make:

Please follow the general coding style adhered to by the existing code.
Please make your changes general whenever possible: if your changes apply to a broad range of Unix variants try to contain them all in your preprocessor conditionals.
Please keep the use of conditional compilation to a minimum. Code with preprocessor directives is harder to read and harder to maintain.

Detailed Build Notes

With the advent of jdk 1.1, and especially differences between releases of jdk 1.1, the process of building toba has become significantly more complicated. This section describes the intent behind the build process that should be supported by the Makefiles, so if something goes wrong, you may be able to see how to fix it. First off, there are some auxiliary packages that you'll need. These are normally distributed with Toba, and should be unpacked and installed during the configuration process, but here's some information on them in case you want to try a different version.

zlib: This is a zip/jar compatible compression library. Get a copy from the zlib homepage. Toba has been tested at various times with versions 1.1.{1,2,3}. After retrieving the source tar file, install it into the Toba main directory thusly (assuming you picked up version 1.1.3):
```
	% rm -f zlib
	% tar xf zlib.tar
	% ln -s zlib-1.1.3 zlib
	% ( cd zlib; ./configure )
```
Version 1.1.3 is provided in the Toba distribution in ./SupFiles, and the above unpacking is done automatically by the configure script.
bnlib: This is Colin Plumb's arbitrary precision arithmetic package, which is required for the BigInteger support in the JDK API. A copy is provided in ./SupFiles, but you could go get the original. The source is under GPL, and is part of the SKIP Simple Key Management for Internet Protocols system. Unpack it thusly:
```
	% rm -f bnlib
	% zcat bnlib-1.1.tar.gz | tar xf -
	% ln -s bnlib-1.1 bnlib
	% (cd bnlib ; patch < ../SupFiles/bnlib-1.1.patch ; ./configure )
```
Again, these steps are done automatically by the configure script.
gc: This is the Boehm-Demers conservative garbage collector. Treat same-same-like above. New versions may be found at http://reality.sgi.com/boehm/gc.html.
BISS: This is a replacement for the JDK AWT classes, including the native windowing support. Although the developers of BISS-AWT are mostly interested in its use as a toolkit, Toba uses it primarily as a basic window system. You should be aware that it is pretty large and is not very reliable in the context in which Toba uses it (many documented AWT methods are not present or are incompletely implemented, and do not work well with the Sun java.awt routines). You'll also need to rebuild a stack of Sun class files to deal with the incestuous relationship between BISS and JDK classes; more about that later.
If you're feeling adventurous and really want to do Java graphics, you'll need two components: the awt-like classes (biss-awt), and the native classes (biss-only). These files are provided in the standard Toba distribution, but are also available from the Linux Java archives. Pick out a nearby server, and follow those links down through biss-awt/biss-0.94. With the two zip files in the ./biss directory, the configuration process involves:
```
	% cd ./biss
	% ./configBiss
```
The configBiss script will unpack the zip files into the locations Toba expects to find them, then apply a patch which fixes several incompatibilities between BISS and the AWT system. This too is done automatically during normal configuration.
You'll also need the Java source for the version of the JDK 1.1 classes you're using. You really do have to match the minor version; rebuilding the 1.1.3 class files and running in a 1.1.6 system is likely to cause you significant grief. The source file should have come with your jdk release, although it may be in compressed form (src.zip). If it didn't, you may be able to find it in the corresponding Linux/i386 tar package; see, for example, this one. Or you can try downloading the Solaris one from the JDK 1.1 homepage and taking the src.zip file from it.

Dragon One: Problem Class Files

Some JDK class files cause problems with the Toba build process. One example is those classes which have large static tables that are initialized in the class initializer. These translate into multi-megabyte C source files that consist primarily of assignments of values into arrays one element at a time, and invariably exceed C compiler limits. The solution is to translate the files once using Toba, then remove the body of the class initializer and replace it with a hand-coded initialization sequence. This is required for java.lang.Character on all known releases of JDK, and also for java.text.DecompositionIterator for releases prior to 1.1.6. Copies of the hand-coded versions of these files are in the ./runtime source directory. If you encounter another, you'll have to add a hand-coded version, and update the necessary configuration variables; look at ./configs/jdk.pre116.opt for an example.

Dragon Two: Class File Interdependencies

Because we're building libraries that expect to find everything they need at link time, we have to be sure that when one class file depends on another, both are included in the translated code. The ./packages/buildAPI script attempts to do this, by listing the classes available from the system class library, excluding certain ones that we don't want (because they're used infrequently, require native library support that is unavailable, or are otherwise troublesome), then determine the transitive closure of the class dependency graph. The result of this is a list of classes that will be translated and linked to build the SUNAPI library. Classes that are not included in this, such as java.beans.*, may still work if they can be found at runtime and if dynamic class loading and JIT'ing is supported on your platform.

Dragon Three: BISS-AWT Support

The BISS AWT package really wasn't intended to support the Sun AWT toolkit, but historically that's how Toba has used it. For JDK 1.1, the native window interface was only available in the 0.94 BISS release. The source files need to be modified to support Toba's native function naming scheme, and to add in some deprecated methods and fields that are referenced in the Sun java.awt classes. Because there are dependencies in both directions between Sun JDK class files like java.awt.Event and BISS-provided class files like java.awt.Component, the API package build process is a complex shell script ./packages/buildAPI. It is fairly well commented; the general process involves rebuilding the BISS classes in your local environment, determining the dependencies amongst all the classes, rebuilding the Sun classes that depend on the replacement BISS classes, and then translating everything to C and linking the two package libraries. Be aware that, if you start to get link error messages about unresolved symbols with strange names, you are probably resolving to a Sun version of a class file when the BISS one is needed instead.

index | usage | differences | native code | implementation | porting | releases | installation || home
http://www.cs.arizona.edu/sumatra/toba/doc/porting.html (July, 1998)