Porting Hints

Toba was designed with portability in mind. The current release supports Irix, Linux, Solaris and Windows NT, although only the Solaris implementation has thread and AWT 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 and the Makefiles in the sub-directories. The top-level Makefile has several definitions used to parameterize the build process. These flags are:

THREADS - The thread interface to use. This parameter is used to construct a file name in the runtime directory. The current release provides definitions for a null (no-op) interface called null and for the Solaris thread interface called sol.
CC - The compiler to use.
CBUILD - The flags to use with the C Compiler when building Toba. Flags that set options in the runtime package are:
- BINARY_LOADER - use dlopen to support dynamic loading. Note that the garbage collector must support dynamic loading to use this option.
- _REENTRANT - use reentrant versions of standard C functions. This flag is required for proper thread support.
- NOTHREADS - optimize away synchronization in single-threaded implementations.
CTOBA - The flags to use with the C Compiler when running Toba. These flags are passed to the compiler when compiling the generated C Code.
TBUILD - The flags to use with the toba script when building Toba.
LIBS - The libraries needed when linking Toba-generated binaries. Any libraries needed to support the threads interface should be included here. Most systems will need to include at least the math library. Libraries linked in implicitly by the compiler (libc, for example) need not be specified.
SLOPT - The linker flag needed to generate a shared library. This flag should be set to the empty string if the toba library is linked statically.
RPOPT - The compiler flag used to embed a shared library path in an executable file. This flag should be set to the empty string if the toba library is linked statically.
LTARG - The target for building the toba library. This may be either shared to build a shared library or static to build a static library.
GCMF - The Makefile and flags for the garbage collector.
PROC - The source files needed to implement the exec method in the runtime. The current release provides two sets of source files: $(UNIXPROC) for the UNIX systems and $(WINPROC) for Windows systems.
SUFFIX - The suffix appended to executables generated by the loader. This is usually the empty string or .exe.
XLIBS - The X libraries needed by the AWT.

The Makefile provides default definitions for each of these flags. Following this is a section defining a target for each target system. A new target should be made when porting to a new system by copying an existing target and tailoring it for the new system. An example entry looks like:

# target for Solaris using Solaris Threads
solaris:
        $(MAKE) all_awt JDK=$(JDK) \
          THREADS=sol \
          CBUILD="-D_REENTRANT -DSOLARIS_THREADS -DBINARY_LOADER \
                  -xlibmieee -Xa -O -K pic" \
          CTOBA="-D_REENTRANT -DSOLARIS_THREADS -xlibmieee -Xa" \
          TBUILD="-O -A'-K pic'" \
          SLOPT="-G"  RPOPT="-R "  LIBS="-lm -lnsl -lsocket -ldl -lthread" \
          XLIBS="-L/usr/openwin/lib -lX11"

Each entry calls make with a target of all (or all_awt) with overriding definitions for the make flags.

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. Two interface definitions are provided: sol and null. The sol package interfaces to the Solaris threads package. The null package is a definition for systems that do not have thread support. When the null package is used the runtime library will not be able to create new Java threads and will exit when thread creation is attempted.

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. The C compiler may also require that certain flags be set when including C header files. These flags should be added to the CBUILD flag at the top level.

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, 1997)