Index of /javadev/nathanw
Name Last modified Size Description
![[DIR]](/icons/back.gif)
Parent Directory 22-May-1997 03:00 -
![[ ]](/icons/unknown.gif)
COPYRIGHT 18-Apr-1995 16:25 3k
![[CMP]](/icons/compressed.gif)
GNUmakefiles.tar.Z 31-May-1995 19:30 11k
LICENSE 19-Apr-1995 16:56 4k
README.GNUmakefiles 31-May-1995 19:29 2k
README.NOW 22-Apr-1995 18:21 1k
README file for Java/HotJava alpha 2 source release
********************************************************************
WARNING: The Java/HotJava alpha 2 source release is an early look
at some new and exciting technology. However, at this stage of its
development the source release itself is not for everybody. It is
not easy to work with, and we know that. Porting it to *any* platform
requires a good understanding of things like threads, synchronization
primitives, asynchronous I/O, GUIs and the like. If you intend to
do serious work on these sources, we ask that you read all of the
following carefully, and preferably contact us directly. For more
information, join the java-porting mailing list for ongoing guidance.
To subscribe to this mailing list, see http://java.sun.com/mail.html
********************************************************************
Building and Running the Alpha 2 Source Release on SPARC/Solaris
----------------------------------------------------------------
The Alpha 2 source release contains the sources for the Java language
and HotJava browser for SPARC-based Solaris 2.3 and 2.4 platforms.
The sources will not work on any other hardware or operating system!
They build using the SunPro C compiler version 3.x and the Solaris
make(1). We haven't tried building with other tools.
If you have any other hardware or software configuration, getting
Java or HotJava to run probably means porting, which is discussed in
a later section. If you have an appropriate hardware and software
configuration, rebuilding the alpha 2 release is easy enough.
You will need two additional software packages before you can
recompile these sources:
1) You need the binary release of Java/HotJava to bootstrap the
source release. The source release uses the environment variable
ALT_BOOTDIR to determine which binary release to bootstrap from.
This will normally be set to <bin-dir>/hotjava, where <bin-dir> is
the directory in which your binary release is installed.
2) You need Motif header files and runtime libraries if you do not
already have them. We have included the Motif package for Solaris
2.3 on SPARC machines in the Java/HotJava source release. See the
section "Installing Motif" below for more information.
Having unpacked the alpha 2 source release in some <src-dir>, you
have created a subdirectory called 'hotjava.src'. You can rebuild
the alpha 2 system by typing:
% cd <src-dir>/hotjava.src/build/solaris
% make
If the make completes without problems, the Java executables will have
been built in 'bin', shared libraries in 'lib', and compiled Java code
(.class files) in 'classes'.
Installing Motif
----------------------------------------------------------------
If your make fails with complaints about not being able to find Motif
include files or libraries, e.g.,
"../../../src/solaris/awt/awt_p.h", line 38: cannot find
include file: <Xm/CascadeB.h>
"../../../src/solaris/awt/awt_p.h", line 39: cannot find
include file: <Xm/DrawingA.h>
[etc]
you may not have Motif installed on your machine. The alpha 2 source
release includes a Motif package for SPARC/Solaris. Note that this
Motif release only contains shared libraries for SPARC-based machines
running Solaris 2.x!
To install the Motif package we have sent, execute the following
commands as 'root':
$ su root
<passwd>
# cd hotjava.src/
# /usr/sbin/pkgadd -d `pwd` SUNWmfrun
Answer 'y' to questions asked during installation of the package. It
is preferable to install the Motif package in the default location of
'/usr/dt'.
If you cannot install Motif in the '/usr/dt', or if you already have
the Motif header files and libraries installed but they are not in
the default directory, you should set the ALT_MOTIF_DIR environment
variable to point to the actual location of the Motif package, e.g.
$ ALT_MOTIF_DIR=/opt/Motif
$ export ALT_MOTIF_DIR
$ make
if Motif is installed in /opt/Motif.
Running HotJava
----------------------------------------------------------------
To run Java and HotJava as built by the source release, you first need
to set some environment variables. These are described more fully in
the man pages in the binary release. The following are reasonable
initial default settings that will allow you to run HotJava:
CLASSPATH .:<src-dir>/hotjava.src/build/solaris/classes
LD_LIBRARY_PATH <src-dir>/hotjava.src/build/solaris/lib:$LD_LIBRARY_PATH
HOTJAVA_HOME <src-dir>/build
In addition, it is assumed that your HOME environment variable is set.
With these environment variables set to the suggested values, you
should be able to change into <src-dir>hotjava.src/build/solaris/bin
and invoke HotJava by typing
% java browser.hotjava
Because the source release doesn't contain all of the documentation that
the binary release does, you won't get the normal HotJava default page,
or many of the other documents. However, the usual "Demos" page and
demo applets are accessible via the Help menu. You can make the full
documentation available to your new build by setting HOTJAVA_HOME to
<bin-dir>/hotjava instead. On reinvoking HotJava you will now see the
normal default page and be able to browse all the documentation included
in the binary release.
If you want to be able to invoke your newly-built HotJava like you
can in the binary release (with "hotjava"), replicate the scripts and
directory structure used in <bin-dir>/hotjava/bin. These scripts
take care of environment variables and redirect output to a log file.
The Java and HotJava Source Hierarchy
----------------------------------------------------------------
If you're interested in how Java or HotJava works, or if you want to
investigate porting to some platform, you should familiarize yourself
with the source hierarchy. The core directory structure (excluding
documentation, demos, generated directories, etc.) is
src -- Java and HotJava sources
share -- Shared Java and HotJava sources
java -- Java language and tool sources
lang -- Basic language classes sources
runtime -- Runtime sources
include -- Include files
awt -- Abstract Windowing Toolkit sources
browser -- HotJava browser sources
net -- Networking sources
solaris -- Solaris-specific Java and HotJava sources
java -- Java runtime and tool sources
main -- Top-level runtime sources
runtime -- Runtime sources
include -- Include files
awt -- Abstract Windowing Toolkit sources
mmedia -- Multimedia Sources
net -- Networking Sources
build -- Java and HotJava build directories and makefiles
solaris -- Solaris build directory and makefiles
awt -- Awt library build directory
browser -- HotJava browser build directory
java -- Java runtime and tools build directory
JAVA -- Java runtime build directory
JAVAH -- Java header generator tool
etc...
makefiles -- Common makefiles
mmedia -- Multimedia library (audio) build directory
net -- Networking library build directory
SUNWmfrun -- SPARC/Solaris Motif 1.2.3 package
The Java and HotJava sources have been organized to minimize the amount
of platform-specific code, and to collect that platform-specific code
in a small number of well-defined places. At the top level of the
source hierarchy there are three directories:
build - makefiles and directories in which to build the sources
src - sources
SUNWmfrun - package containing Motif 1.2.3 libraries, headers, etc.
The 'SUNWmfrun' directory only needs to be considered if you don't have
the Solaris Motif libraries, header files, etc. installed on your machine.
The 'build' and 'src' directories each contain one subdirectory per
target platform. In the initial source release those subdirectories are
named 'solaris', and contain the building tools and source files,
respectively, for the SPARC/Solaris version of Java and HotJava. In
addition to the platform-specific subdirectories, there is a subdirectory
'share' under 'src'. This directory contains the sources that are shared
across all ports of Java and HotJava.
The files in the 'build/solaris' directory are mostly makefiles and
make-related files. Running make in the 'build/solaris' directory
builds all of Java and HotJava. Running make in 'build/solaris/java'
builds the Java language, tools and basic libraries. Within
'build/solaris/java' individual tools can also be built: the java
interpreter in the JAVA directory, javah in JAVAH, etc.
The 'build/solaris' directories that contribute directly to HotJava
include 'awt', 'browser', 'demo', 'doc', 'mmedia' and 'net'. These
can be built individually or via the higher-level makefile. The
'makefiles' directory contains common makefile components included by
many other makefiles elsewhere within the build.
There are structural similarities in the 'src/solaris' directory.
The 'java' subdirectory contains Solaris-specific code for the the
Java language, tools and library sources. The 'awt', 'mmedia' and
'net' subdirectories contain Solaris-specific parts of the HotJava
browser.
The 'src/share' directory is also organized similarly, and includes
code that is common to HotJava or Java on any platform.
For More Information on Porting
----------------------------------------------------------------
Before beginning to discuss porting, we acknowledge that what will
follow will certainly be inadequate to ease you through a port. If
you intend to work seriously on a port, we suggest that you contact
us directly and join the java-porting or java-porting-digest mailing
list run by majordomo off java.sun.com. Archives of those groups are
available at http://java.sun.com/ . We also intend to add information
related to porting to our web pages on java.sun.com as it is developed.
Porting Java
----------------------------------------------------------------
The Java runtime, or Java interpreter, enables Java programs to run.
Because the Java compiler and HotJava are Java applications, the
runtime must work before either can run. However, because the Java
compiler is just a Java application, once the runtime has been ported
the compiler should work immediately.
If you have a SPARC/Solaris machine and appropriate software available,
and haven't done so already, it is a good idea to try to rebuild the
Solaris alpha 2 from the sources to familiarize yourself with the
original build process before starting a port.
Any port begins with the replication of the 'build/solaris' and
'src/solaris' hierarchies under a new name describing your target
platform, e.g. 'build/linux' and 'src/linux'. The entire directory
structure should be replicated. Note, though, that all the files in
the original 'solaris' subdirectories are Solaris-specific, and are
likely to need significant modification or complete replacement for
your new platform.
In the Java runtime, the interface between shared and platform-specific
source code is known as the Host Programming Interface, or HPI, and
is defined by the file src/share/java/include/sys_api.h. A port of
the Java runtime is essentially an implementation of the HPI as defined
by sys_api.h.
IMPORTANT: If you ever intend to share changes to the alpha 2 source
release with anybody else, including us, it is vital that you retain
our distinction between shared and platform-specific code. You are
not expected to have to change code in the 'src/share' subdirectory;
changes to it should be strongly resisted. You also should not need
to change the HPI, and should avoid doing so if at all possible.
It is not necessary that a port implements all the internal machinery
present in the Solaris-specific files. For instance, where a platform
has native condition variables it is unlikely that a clock/timer thread
will be needed at all. If functionality present in files in the Solaris
system isn't needed, the files should be deleted. If functionality
must be added, new files should be created. We don't assume that our
choice of files for Solaris should reflect the structure of any other
port.
The Solaris makefiles are written using the Solaris make(1), and are
known *not* to work with gnumake. Our current practice is to use the
native make tools on the target plaform -- e.g. on Win32 we use nmake.
However, it might be a good idea to try using gnumake in the hope that
it could assist subsequent ports.
If you use libraries supplied from elsewhere, e.g. a threads implementation,
be sure to retain all appropriate copyright notices and credits. If you
use any code which restricts redistribution rights, be sure that works
for your purposes. We prefer to redistribute your work widely, so the
fewer restrictions on code the better.
Porting HotJava
----------------------------------------------------------------
A port of HotJava consists mainly of a port of the Abstract Windowing
Toolkit, the networking library and the multimedia library. These
are naturally implemented as shared objects (.so's) on Solaris, DLL's
on Win32, etc. You should use the tools and techniques that are
appropriate for your platform.
Unlike the Java runtime, the APIs for the HotJava libraries are
defined by the interface between shared Java and platform-specific
C code. You should not need to modify the Java code, but are free
to write supporting C code as is appropriate for your platform. The
next section goes into some detail on how to approach a port of the
AWT. Ports of the networking and multimedia libraries are similar,
although much simpler.
Porting the AWT
----------------------------------------------------------------
Much of the AWT toolkit, such as the layout manager, is written in Java.
However, to achieve a natural look-and-feel on various platforms, the AWT
currently relies heavily on the platform's native user interface widgets,
such as buttons, menus, and scrollbars. For example, the AWT uses Motif
widgets on Solaris, and on the PC, MS Windows controls. There are
presently about a dozen user interface widgets in the AWT toolkit and so
porting the AWT basically involves writing wrappers around the analog
widgets supplied by your platform. If your platform does not support a
certain widget, you need to write the code to simulate the widget.
All the functionality that's required from your platform is encapsulated
in a single class called WServer. This class lives in a file called
WServer.java. All AWT-related calls to platform-specific code are
directed through methods in this class. There are about 170 native
method calls that you need to implement. We've provided a C header
file, "awt.h", that give C prototypes for each of these methods.
The connection between WServer and your platform-specific AWT code is
via the stub file "libstubs.c" in the 'build' subdirectory of the
awt branch. There is a stub for each of the native calls in WServer.
The name of a stub is generated from the name of the native call; e.g.
the stub for the Java native method awt.WServer.frameShow is named
awt_WServer_frameShow_stub. This stub calls your platform-specific
code which has names and prototypes of the form specified "awt.h".
You need to link your implementation of the AWT native methods and
libstubs.c in a single dynamic-link library called awt.<extension>.
Here are some problems you need to address as you port the AWT:
- Changes for beta. You currently have an alpha version of the AWT.
We are planning to make extensive changes to AWT, and you should
expect that your AWT port will have to be reworked significantly.
However, your experience hooking up the alpha AWT to your platform's
UI system will very likely be useful when porting to beta.
- Fonts. The AWT supplies its clients with a half a dozen fonts in
arbitrary point sizes. You need to map these logical fonts to fonts
on your platform. If you don't have scalable fonts, you need to deal
with requests for different point sizes, e.g. you might have to map
the requested size to the closest available point size.
- Multi-threading. The AWT assumes that any thread can operate on a
widget, regardless of which thread created the widget. This isn't a
problem with Motif, for example, but required some thought on Win32.
Unless your code creates threads, you don't need to worry about
synchronizing calls from AWT clients. There is a monitor on WServer
and since all calls to your platform-dependent code is through
synchronized methods in WServer, none of your platform-dependent
code will be called simultaneously from multiple threads. (This is
obviously too restrictive and we plan to make the interface allow
more concurrecy in the future.)