README
Java® 2 SDK, Standard Edition
Community Source Release

Contents

Introduction Contents of the Source Release Building the Source Release Using the SDK Troubleshooting Build Problems Building Other Targets

Updates and errata to this README will be made available on-line.

Welcome to the first release of the buildable source code for the Java® 2 SDK. This source code is provided as part of the Sun Microsystems Community Source Licensing program. The new licensing model:

• Allows commercial entities to use and modify the source code for commercial software product development without charge.

• Allows innovation on the source code without requiring that innovation be returned to Sun.

• Allows commercial entities to modify and share compatible source code with other commercial entities without charge and without mediation from Sun.

• Allows licensees to package for resale Sun's Java platform class libraries with virtual machines from other licensees.

Please see the Sun Community Source License on the Sun website for full details about the provisions and requirements of the new licensing program:

Sun Community Source License

This community source release contains all the source code and makefiles required for building the Java 2 SDK. By following the build instructions below, you can generate the Java virtual machine, class libraries for the platform API, and development tools that you would find in the Java Software releases of the Java 2 SDK binaries.

The next section describes the contents of the Java 2 Community Source Release. You can review that first, or jump straight to the build instructions. After you've successfully completed a build, you can refer to the section on Using the SDK for information about where to find and how to use the binary files that are produced by the build.

The source release contains five top-level directories.

The build directory
The build directory contains the makefiles that are needed for building the SDK. Make files that are shared between Solaris and Win32 platforms are contained in the build/share directory. Solaris-specific makefiles are in the build/solaris directory, and Win32-specific makefiles are in the build/win32 directory. The build/solaris directory contains makefiles for building both the SPARC and x86 versions of the Solaris SDK.

The ext directory
This directory contains the source code and makefiles for building the auxiliary libraries that are included with the SDK. These libraries are the internationalization library (bundled as i18n.jar in the SDK) and the Internet-Intranet Input Method Protocol standard extension (bundled as iiimp.jar in the SDK).

The src directory
This directory contains the C and Java language source code for building the SDK. As with the build directory, it contains share, solaris, and win32 directories for shared files, Solaris-specific files, and Win32-specific files.

Building the community source release involves running the makefile scripts that compile the source code and generate the libraries and tools that comprise the Java 2 Standard Edition SDK. After building the release, you'll have everything that ships as part of the SDK as you'd download it from the Java Software website.

You can build three versions of the SDK with this community source release:

• Win32
• Solaris-Sparc
• Solaris-x86

If you're on a Solaris platform, the Solaris-specific makefiles will automatically determine whether they're running on a SPARC machine or on an x86 machine and build the appropriate version. Therefore, only two sets of build instructions are required:

• Build instructions for the Win32 version of the SDK
• Build instructions for the Solaris-SPARC and Solaris-x86 versions of the SDK

Build instructions for the Win32 version of the SDK

You need to perform the build on a Windows NT 4.0 platform. After the build is completed, you can run the binaries on any Win32 operating system. The minimum recommended hardware for building the Win32 version is a PC with a Pentium class processor and 128 megabytes of RAM.

Pre-build requirements

You must satisfy these requirements before you can build the Win32 version of the SDK:

• You need to have the following tools that are used by the build process:
  • Microsoft Visual C++ version 5.0 for compiling C code. Though this software is required for compiling C code, the build is done using Microsoft nmake rather than with the Microsoft Visual C++ IDE.
  • Microsoft Assembler version 6.11.
  • Microsoft VisualStudio 97 Service Pack 3 for Java2D functionality.
  • MKS Toolkit version 5.2 (http://www.mks.com) for Unix emulation on the Windows NT platform.
  You'll need to ensure that these tools are on your path. The MKS Toolkit should be first in your path followed by Microsoft Visual C++ or the WinNT system directory in either order. Last on the path should be the Microsoft Assembler. Here's an example of how you can set up your path for the build. This example assumes that you've installed the tools as follows:

  Microsoft Visual C++ in C:\Program Files\DevStudio
  MKS ToolKit in C:\mksnt
  Microsoft Assembler in C:\masm611

  With these assumptions, you could prepare your system for the build by entering the following commands at the DOS prompt. (The line breaks in the longer commands are present so they'll fit on the page if you print these instructions. You should not, of course, include the line break in the actual commands.)

  set MSVCDir=c:\Program Files\DevStudio\VC
  
  set MSDevDir=c:\Program Files\DevStudio\SharedIDE
  
  set WindowsDir=c:\winnt
  
  set include=%MSVCDir%\include;%MSVCDir%\mfc\include;
  %MSVCDir%\atl\include
  
  set lib=%MSVCDir%\lib;%MSVCDir%\mfc\lib
  
  set PATH=c:\mksnt;%MSVCDir%\bin;%MSDevDir%\bin;%WindowsDir%\system32;
  c:\masm611\bin;%PATH%
  

• You need a binary version of the Win32 JDK 1.2 software with which to bootstrap the build. You can download a copy of the JDK 1.2 software from the Java Software website. Once the JDK 1.2 software is installed on your system, you need to set the ALT_BOOTDIR environment variable to point to its top-level directory. For example, if you've installed the JDK 1.2 software in C:\jdk1.2, you need to do this:

  set ALT_BOOTDIR=C:\jdk1.2
  

• You should ensure that environment variables CLASSPATH and JAVA_HOME are not set.

• The MKS Toolkit will create temporary files during the build. You can specify a location to place these temporary files by using the TMPDIR environment variable, as in this example:

  set TMPDIR=C:\temp
  

Building the SDK

Once you've met the pre-build requirements, there are only a few simple steps to follow to do the build.

1. Change to the build\win32 directory of the source release. For example if your source release is installed in C:\jdk1.2-src:

   cd C:\jdk1.2-src\build\win32
   

2. Launch the build process by entering this at the command prompt:

   nmake world
   

   You can expect the build to take as long as one or more hours, depending on your system hardware.

If you do subsequent builds, it's a good idea to first remove all the files that were produced by the previous build. The makefiles will do this for you if you run this command from the build\win32 directory:

nmake world-clobber

Build instructions for the Solaris versions of the SDK

The Solaris makefiles will automatically determine whether they're running on a SPARC machine or on an x86 machine and build the appropriate version of the SDK. You can follow these build instructions on either Solaris-SPARC or Solaris-x86. You can do the build on Solaris 2.5.1 or Solaris 2.6. The minimum recommended hardware for building the Solaris-SPARC version is an UltraSPARC with 128 megabytes of RAM. For building the Solaris-SPARC version, a Pentium class processor or better and at least 128 megabytes of RAM are recommended.

Pre-build requirements

You must satisfy these requirements before you can build a Solaris version of the SDK:

• You need the GNU make utility (gnumake), version 3.74 or later. You can ftp this from prep.ai.mit.edu. The Solaris makefiles are written using gnumake and will not work with Solaris make.

• You need the Sun C compiler version 4.2. This compiler is available at http://www.sun.com/workshop/compilers_c/ and is also part of recent releases of WorkShop Professional^TM C and Visual WorkShop^TM C++.

• You need a binary version of the Solaris JDK 1.2 software with which to bootstrap the build. You can download a copy of the JDK 1.2 software from the Java Software website. Once the JDK 1.2 software is installed on your system, you need to set the ALT_BOOTDIR environment variable to point to its top-level directory. For example, if you've installed the JDK 1.2 software in /java/jdk1.2, you need to do this:

  setenv ALT_BOOTDIR /java/jdk1.2
  

• You will need Motif header files and runtime libraries (libXm). Use the ALT_MOTIF_DIR environment variable to point to the location of your Motif package. For example:

  setenv ALT_MOTIF_DIR /usr/dt
  

• The build process uses the tools contained in the Solaris /usr/ccs/bin directory. This directory and its contents are part of the standard developer or full installation of the Solaris operating system. You should ensure that this directory is present and that it is on your path.

• You will need the JDBC-ODBC Bridge driver, ODBC2.11, for building the JDBC-ODBC packages. A copy of the driver is on the Desktop 1.1.1 Solaris CD-ROM which is part of the normal Solaris distribution. Set the ALT_ODBCDIR environment variable to point to it. For example, if the driver is installed in /opt/jdkb-odbc:

  setenv ALT_ODBCDIR /opt/jdbc-odbc
  

• You should ensure that the CLASSPATH and JAVA_HOME environment variables are not set.

Building the SDK

Once you've met the pre-build requirements, you can start the build with a few simple steps.

1. Change to the build/solaris directory of the source release. For example if your source release is installed in /java/jdk1.2-src:

   cd /java/jdk1.2-src/build/solaris
   

2. Launch the build process by entering this at the command prompt:

   gnumake world
   

   You can expect the build to take as long as one or more hours, depending on your system hardware.

If you do subsequent builds, it's a good idea to first remove all the files that were produced by the previous build. The makefiles will do this for you if you run this command from the build/solaris directory:

gnumake world-clobber

New directories are created when you successfully build any version of the SDK.

The bin directory
You'll find this directory inside the directory from which you started the build, either build\win32 on Win32 platforms or build/solaris on Solaris platforms. The bin directory contains all the executable files for the SDK development tools that are created during the build. Both optimized and debug versions of the tools are produced. These tools include the java interpreter, the javac compiler, and the other tools of the SDK. Put the bin directory on your path to use the tools you've built. Documentation for using these tools is available on the Java Software website

The lib directory
This directory is created at build\win32\lib on Win32 platforms and at build/solaris/lib on Solaris platforms. It contains libraries used by the Java 2 Standard Edition platform. This libraries include i18n.jar for internationalization support, font properties files, the ext directory containing the iiimp.jar standard extension and other resources used by the Java platform.

The classes directory
This directory contains bytecodes (.class files) for all Java source code that was compiled during the build. It's contents correspond to the files contained in the SDK's rt.jar file.

Other directories containing compiled bytecodes are created within the directory structure beneath the top-level ext directory.

Once the community source release is built, you can use the resulting SDK much as if you were using the Java 2 Standard Edition platform that you can download and install in binary form. Complete documention for the Java 2 SDK is available on the Java Software website

A build can fail for any number of reasons. If you can't determine what's causing the problem, go back through the list of pre-build requirements to see if they're all met. Check that you don't have the CLASSPATH and JAVA_HOME environment variables set. If you've built the source before, make sure that you've done a "clobber" before building again. To clobber on Win32, issue this command from the build\win32 directory:

nmake world-clobber

On Solaris, issue this command from the build/solaris directory:

gnumake world-clobber

Here are a few error messages that can result if something goes awry during a build. Beneath each message is a brief explanation of what might be the cause of each problem.

• /usr/ucb/cc: language optional software package not installed

  (Solaris only) This message is a possible indication that you don't have the correct C compiler version 4.2 installed or that it's not on your path (or near enough to the front of your path).

• ERROR: Your Microsoft Visual C++ compiler predates the 5.0 release

  (Win32 only) To do a build on a Win32 system, you must use version 5.0 of Microsoft Visual C++. If you have version 5 on your path and you still get this error, if may be due to your tools having been mounted via the Solstice NFS client rather than by a local installation. Install the tools locally, update your path, and the problem should go away.

• ERROR: You have not installed Microsoft Visual Studio 97 service pack 3

  (Win32 only) Self-explanatory. Recall that service pack 3 is required because it fixes bugs that were adversely affecting Java2D functionality.

In addition to the makefiles for building the Java 2 Standard Edition SDK, the community source release contains makefiles for building other sets of binaries and files. The following list shows some of the build "targets" for which makefiles exist in the source release. To build any of these targets, go to the build\win32 directory on Win32 platforms or the build/solaris directory on Solaris platforms and run this command:

On Win32: nmake <target>
On Solaris: gnumake <target>

In these commands, <target> stands for world, all or any other target described in the following list.

world

This is the target for the full SDK. This target is a combination of the all and ext targets.

all

This target builds the optimized and debug versions of the Java 2 Standard Edition platform, without building any extensions.

ext

This generates optimized and debug versions of extensions.

releasedocs

This target uses the Javadoc utility to generate HTML-formatted API documentation for the public platform API. The build places this documentation in the bin/doc/api directory.

release-images

This target produces complete copies of both the Java 2 SDK and the Java 2 runtime environment exactly as they would appear if the SDK and JRE binaries were downloaded from the Java Software website and installed.