Porting Hints
Toba was designed with portability in mind.
The current release supports Solaris and Linux,
although the Linux implementation lacks thread 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
and
runtime/monitor.c
.
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.
- 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.
- RPOPT - The compiler flag used to embed a shared library path
in an executable file.
- GCMF - The Makefile and flags for the garbage collector.
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 \
THREADS=sol \
CBUILD="-D_REENTRANT -DSOLARIS_THREADS -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"
Each entry calls make
with a target of all
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.ksh
file.
If you need to make changes to the driver script you should
edit the bin/toba.ksh
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 (December, 1996)