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.0.2 of the Java Developers Kit on the host platform. Cross-building to a different target platform is not supported. Toba will not work with version 1.0.1 or 1.1 of the JDK.

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.

AWT

Toba uses the BISS AWT package to provide AWT support. 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, 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. Platform-specific configurations are provided for:

Linux 2.0/Intel: linux.mk for full JIT and thread support using Scout threads; linux-nojit.mk for Toba without JIT, and linux-nothread.mk for Toba with neither JIT nor threads.
Irix 6.2/MIPS: irix.mk for Toba without JIT but with Irix threads.
Solaris 2.5/SPARC: solaris_gcc.mk for Toba without JIT but with Solaris threads, using GNU cc for compilation, and solaris.mk for the same system using Sun's C compiler.

To build for a new system, create a new configuration file that overrides the default compilation settings, and change the configs/current.mk symlink to point to the new file. The Makefile target all builds the entire Toba system except for AWT support; the target all_awt adds AWT.

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_package.c and runtime/sthreads_package.h where package is the thread interface package defined in the top level Makefile. During the build a link is made from sthreads.c and sthreads.h to one set of these files. Several interface definitions are provided:

irix: Irix 6.2 native thread support. Set the Makefile THREADS to irix and add -DIRIX_THREADS to the Makefile CBUILD variable.
null: A dummy target when no native thread support is available. Set the Makefile THREADS to null and add -DNOTHREADS to the Makefile CBUILD variable.
scout: The Scout thread interface. Currently works only on Linux 2.0, or in the Scout operating system. In current.mk, set:
- THREADS to scout
- add -DSCOUT_THREADS to CBUILD
- set EXTRA_TARGETS to scout_threads
- set RTLDFLAGS to ../scout_threads/*.o `cat ../scout_threads/ccflags`
sol Solaris 2.x native thread support. Set the Makefile THREADS to sol and add -DSOLARIS_THREADS to the Makefile CBUILD variable.

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.

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.

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