README

JavaTM 2 SDK, Standard Edition, v1.3.1
Community Source Release


See the most up-to-date version of these build notes online at
http://java.sun.com/j2se/1.3/scsl/README.html.

Contents

This README contains the following sections.

Introduction

This source code for the JavaTM 2 SDK, Standard Edition, (J2SETM) v1.3.1 is provided as part of the Sun Community Source Licensing program. Please see the Sun Community Source Licensing web site for full details about the provisions and requirements of this licensing program:
Sun Community Source License

Contents of the Community Source Release

This community source release contains all the source code and makefiles required for building the Java 2 SDK and the associated Java HotSpotTM virtual machines on the following platforms:

In addition, the source code for building the Java Plug-in product is provided for Solaris and Linux platforms.

The source release has the following top-level directories.

hotspot1.3.1
The hotspot1.3.1 directory contains the source code and makefiles necessary for building the Java HotSpot Client VM and the Java HotSpot Server VM.
j2sdk1.3.1
The j2sdk1.3.1 directory contains the source code and makefiles necessary for building everything in the Java 2 SDK 1.3.1 except the VMs, including runtime libraries, tools and utilities.


For Microsoft Windows users: File os_share_win32.hpp, located at src\os\share\win32\vm in the Java HotSpot source tree, is a zero-length empty file. This file is empty intentionally, and it must be present in order for the build on Windows NT to work. However, some zip utilities such as WinZip 8.0 will not extract zero-length files. You should check to ensure that the zip utility you used to unpack the source bundle extracted this file. If you do not see this file in your distribution, you should create a zero-length, empty file at src\os\share\win32\vm\os_share_win32.hpp.

Doing a full build is a two-step process.

  1. Building the Java HotSpot VMs -- First you will need to build the Java HotSpot Client and Server VMs by using the makefiles in the hotspot1.3.1 directory.

  2. Building the Java 2 SDK -- After the VM binaries are built, you will build the remainder of the Java 2 SDK 1.3.1 by using the makefiles in the j2sdk1.3.1 directory. These makefiles will produce the libraries and tools of the Java 2 SDK and will incorporate into the build the VM binaries produced in step 1.

Building the Java HotSpotTM Virtual Machines

The first step in building a complete J2SE v1.3.1 is to build the Java HotSpot Client VM and Java HotSpot Server VM. The source code and makefiles for building the VMs are located in the hotspot1.3.1 directory of your J2SE v1.3.1 community source installation. Inside that you will find build/solaris, build/win32_i486, and build/linux directories from which you can build the Java HotSpot VMs on the respective platforms.

Pre-build requirements and instructions for building the Java HotSpot VMs are provided in the following sections:

Building for the SolarisTM Operating Environment
Building for Microsoft Windows
Building for Linux

Building the Java HotSpot VMs for the Solaris Operating Environment

The Java HotSpot Virtual Machines support SPARC-V8 and SPARC-V9 hardware, running on Solaris 2.6, Solaris 7, or Solaris 8. It is not supported on Solaris 2.5.1. It is recomended your machine have 64MB of RAM or more.

You should have version 5.0 of the Sparc C++ compiler and version 3.78.1 or later of the GNU make utility (gnumake). Information and access to ftp download sites for GNU make are available on the GNU Make web site. The Solaris makefiles are written using gnumake and will not work with Solaris make. The compiler and Gnu tools should be in your PATH.

You can build the Java HotSpot virtual machines on Solaris 2.6, Solaris 7, or Solaris 8.


Note: The Java HotSpot VM binaries will not work on earlier versions of Solaris than that from which they were built. For example, binaries built on Solaris 2.6 will work on Solaris 2.6, Solaris 7, and Solaris 8; binaries built on Solaris 7 will work on Solaris 7 and Solaris 8, but not on Solaris 2.6, etc.

You should have the following Solaris 2.6 or Solaris 7 patches installed before you build the Java HotSpot VMs and the Java 2 SDK. No patches are required for building on Solaris 8. Later revisions of the patches are expected to work also, although the build has not been tested on later patch revisions.

Patches for Building on Solaris 2.6
SPARC patchx86 patchDescription
105210-27 105211-27 LibC patch
105284-33 105285-33 Runtime library (Motif) patch
105568-17 105569-16 Threads patch
105591-09 104678-07 C++ library patch
105633-38 106248-27 Xserver patch
105669-10 105670-09 libDTSvc patch
106040-13 106041-13 Input-methods patch
106125-09 106126-09 Patch for patch database
106409-01 106410-01 Chinese font fix
106841-01 105200-11 Euro-support patch
106842-09 106844-05 Threads patch
107733-06 105491-05* Linker patch
108091-03 108642-03 X18N_OBJS patch
105181-20 105182-20 Kernel update
* After revision 09, patch 105491 was superseded by patch 107734.

Patches for Building on Solaris 7
SPARC patchx86 patchDescription
106327-08 106328-08 C++ library patch
106950-09 106951-09 Linker patch
106980-10 106981-10 Libthreads patch
107081-20 107082-20 Motif and runtime library patch
107153-01 107152-01 Chinese font patch
107226-12 107227-12 CDE window manager patch
107544-03 107545-03 Kernel update
107636-03 107637-03 X input-method patch
108374-04 108375-04 CDE libDtWidget patch
108376-07 108377-07 OpenWindows patch
109104-01 109105-01 Kernel update
106541-11* 106542-11* Kernel update
* A reboot is required after installation of patches 106541 and 106542.

To build the Java HotSpot VMs, perform the following steps.

  1. You need the J2SE v1.3.0 for Solaris binary release with which to bootstrap your build. Once J2SE v1.3.0 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 have installed the bootstrap Java 2 SDK in /usr/j2se, you need to do this:
    setenv ALT_BOOTDIR /usr/j2se
    
    You must also go to the jre/lib/<arch>/native_threads directory of your bootstrap installation (where <arch> stands for either sparc or i386) and create the following symbolic link:
    ln -s libhpi.so libhpi_g.so
    

  2. Unset the CLASSPATH and LD_LIBRARY_PATH environment variables.
    unsetenv CLASSPATH
    unsetenv LD_LIBRARY_PATH
    
  3. Change directories to the location of the build scripts.
    cd build/solaris
    
  4. Run the build script.

    To build the Java HotSpot Server VM:

    gnumake product
    

    To build the Java HotSpot Client VM:

    gnumake product1 
    

    Near the end of the output for the product build, a message will indicate that "test" is being skipped. This is expected and does not indicate a build error.

  5. Build the debug version of the VM.

    First, set the JAVA_HOME environment variable to the top-level of the bootstrap Java 2 SDK that you installed in step 1. This means that JAVA_HOME will be set to the same value as ALT_BOOTDIR.

    To build the debug version of the Java HotSpot Server VM:

    gnumake jvmg
    

    To build the debug version of the Java HotSpot Client VM:

    gnumake jvmg1 
    

After the build is finished, you will find the binary files for the Java HotSpot VM at the following locations (<arch> stands for either sparc or i486, depending on your platform).

Java HotSpot Server VM
The binary file for the Java HotSpot Server will be at
solaris_<arch>_compiler2/product/libjvm.so
The debug version will be at
solaris_<arch>_compiler2/jvmg/libjvm_g.so

Java HotSpot Client VM
The binary file for the Java HotSpot Server VM will be at

solaris_<arch>_compiler1/product/libjvm.so
The debug version will be at
solaris_<arch>_compiler1/jvmg/libjvm_g.so

Building the Java HotSpot VMs for Microsoft Windows

You must build the Java HotSpot Virtual Machines on a Windows NT 4.0 platform with NT Service Packs 3, 5, or 6a. You should not have Service Pack 4. Once the VMs are build, you may use them on any Win32 platform. The minimum recommended platform for building the Java HotSpot VMs is a PC with a Pentium class processor and 48 megabytes of RAM.

You will also need the following.

To build Java HotSpot Client VM, open Command Prompt and enter the following commands:

C:\>mkdir c:\builds
C:\>cd c:\builds
C:\builds>set HotSpotWorkSpace=<full path to communtity source hotspot1.3.1 directory>
C:\builds>%HotSpotWorkSpace%\build\win32_i486\build compiler1 %HotSpotWorkSpace% <path to bootstrap J2SE>
The build will produce files jvm.dll and jvm_g.dll in C:\builds\hotspot_compiler1\bin.

To build Java HotSpot Server VM, run this additional command:

C:\builds>%HotSpotWorkSpace%\build\win32_i486\build compiler2 %HotSpotWorkSpace% <path to bootstrap J2SE>
The build will produce files jvm.dll and jvm_g.dll in C:\builds\hotspot_compiler2\bin.

To complete preparation for the J2SE build, you must manually copy the Xusage.txt files into these VM build directories, as follows:

COPY %HotSpotWorkSpace%\src\share\vm\Xusage.txt C:\builds\hotspot_compiler1\bin
COPY %HotSpotWorkSpace%\src\share\vm\Xusage.txt C:\builds\hotspot_compiler2\bin
The Xusage.txt files contain help messages for the command-line options recognized by the VM.

Building the Java HotSpot VMs for Linux

To build the Java HotSpot VMs for Linux, a Pentium class processor or better and at least 128 megabytes of RAM are recommended. It is also recommended that builds be done on Linux kernel 2.2.12 or later, with C library glibc 2.1.2.

Perform the following steps to build the Java HotSpot VMs.

  1. You need the J2SE v1.3.0 for Linux binary release with which to bootstrap the build. Once the bootstrap Java 2 SDK 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 have installed the Java 2 SDK in /java/jdk1.3.0, you need to do this:
    setenv ALT_BOOTDIR /java/jdk1.3.0
    

  2. Unset the CLASSPATH and LD_LIBRARY_PATH environment variables.
    unsetenv CLASSPATH
    unsetenv LD_LIBRARY_PATH
    

  3. Change directories to the location of the build scripts.
    cd build/linux
    

  4. Run the build script.

    To build the Java HotSpot Server VM:

    gnumake product
    

    To build the Java HotSpot Client VM:

    gnumake product1 
    
  5. Build the debug version of the VM.

    To build the debug version of the Java HotSpot Server VM:

    gnumake jvmg
    

    To build the debug version of the Java HotSpot Client VM:

    gnumake jvmg1 
    

    After the build is finished, you will find the binary files for the Java HotSpot VM at the following locations.

    Java HotSpot Server VM
    The Java HotSpot Server VM binary file will be at
    build/linux/linux_i486_compiler2/product/libjvm.so
    
    The debug version will be at
    build/linux/linux_i486_compiler2/jvmg/libjvm_g.so
    

    Java HotSpot Client VM
    The Java HotSpot Server VM will be at

    build/linux/linux_i486_compiler1/product/libjvm.so
    
    The debug version will be at
    build/linux/linux_i486_compiler1/jvmg/libjvm_g.so
    

    Following the completion of the product, product1, jvmg, and jvmg1 builds, you must create a bootstrap directory for the VMs in preparation for the J2SE build. Do this by creating the following directories and links.

    setenv ALT_HOTSPOT_CLIENT_PATH hotspot_client_bootstrap
    mkdir $ALT_HOTSPOT_CLIENT_PATH 
    cd $ALT_HOTSPOT_CLIENT_PATH 
    ln -s <scsl_home>/hotspot1.3.1/build/linux/linux_i486_compiler1/jvmg/libjvm_g.so libjvm_g.so
    ln -s <scsl_home>/hotspot1.3.1/build/linux/linux_i486_compiler1/product/libjvm.so libjvm.so
    ln -s <scsl_home>/hotspot1.3.1/src/share/vm/Xusage.txt Xusage.txt
    cd ..
    
    setenv ALT_HOTSPOT_SERVER_PATH hotspot_server_bootstrap
    mkdir $ALT_HOTSPOT_SERVER_PATH 
    cd $ALT_HOTSPOT_SERVER_PATH 
    ln -s <scsl_home>/hotspot1.3.1/build/linux/linux_i486_compiler2/product/libjvm.so libjvm.so
    ln -s <scsl_home>/hotspot1.3.1/build/linux/linux_i486_compiler2/jvmg/libjvm_g.so libjvm_g.so
    ln -s <scsl_home>/hotspot1.3.1/src/share/vm/Xusage.txt Xusage.txt
    cd ..
    

    Building the Java 2 SDK

    Building the community source release involves running the makefile scripts that compile the source code and generate the libraries and tools that comprise J2SE v1.3.1. The source code and makefiles for building J2SE v1.3.1 are located in the j2sdk1.3.1 directory. This directory has the following subdirectories.

    make
    This directory contains the makefiles that are needed for building J2SE v1.3.1. You will launch the build from inside this directory.

    ext
    This directory contains the source code and makefiles for building auxiliary software that is included with J2SE v1.3.1. This includes the internationalization library, software related to the JavaTM Platform Debugger Architecture product, and Java Plug-in software (on Unix platforms).

    src
    This directory contains the C and Java-language source code for building J2SE v1.3.1.

    An important part of doing successful builds is making sure you have met all pre-build requirements.

    Pre-build Requirements for the Solaris Operating Environment
    Pre-build Requirements for Microsoft Windows
    Pre-build Requirements for Linux

    Pre-build Requirements for the SolarisTM Operating Environment

    The minimum recommended hardware for building the Solaris-SPARC version is an UltraSPARC with 128 megabytes of RAM. For building the Solaris-x86 version, a Pentium class processor or better and at least 128 megabytes of RAM are recommended.

    You must satisfy these requirements before you can build J2SE v1.3.1 on Solaris:

    • The official build platform is Solaris 2.6, and Sun has done testing only on this platform. However, successful builds are known to have been done on Solaris 7 and Solaris 8. Note, however, that the J2SE v1.3.1 binaries will work only on the version of Solaris on which they were built, or a later version. Binaries built on Solaris 2.6, for example, will work on Solaris 2.6, Solaris 7, and Solaris 8; binaries built on Solaris 7 will work on Solaris 7 and Solaris 8, but not on Solaris 2.6, etc. Building on Solaris 2.5.1 or earlier is not supported.

    • If you are building on Solaris 2.6 or Solaris 7, ensure that the Solaris patches specified above in the Java HotSpot VM build instructions are installed.

    • You need the GNU make utility (gnumake), version 3.78.1 or later. Information and access to ftp download sites for GNU make are available on the GNU Make web site. Solaris make will not work.

    • You need the Sun Workshop C/C++ compiler version 5.0, with the ALT_COMPILER_PATH environment variable set to its location. You need the following compiler patches installed. Minimal patch versions are listed if known.

      Solaris version SPARC patch X86 Description
      2.6, 7 107357-03 107830 Compiler Common 5.0: Patch C 5.0, C++ 5.0, F77 5.0, F90 2.0
      2.6, 7 107390-04 none C++ 5.0: Patch for 64-bit C++ 5.0 compiler
      2.6, 7 107311-05 107312 C++ 5.0: Patch for C++ 5.0 compiler
      2.6 105591-05 104678 SunOS 5.6: Shared library patch for C++
      2.6, 7 107295-01 107296 WorkShop IPE 5.0: Patch for WorkShop IPE 5.0
      2.6, 7 107354-01 107360 TeamWare 2.1: Patch for TeamWare 2.1
      7 106327-05 106328 SunOS 5.7: Shared library patch for C++
      7 106300-06 none SunOS 5.7: Shared library patch for 64bit C++
      7 107058-01 none SunOS 5.7: Patch for assembler
      2.6, 7 107289-03 107290 C 5.0: Patch for C 5.0 compiler
      2.6, 7 107355-02 107361 WorkShop IPE 5.0: Patch for dbx
      2.6, 7 107742-01 none WorkShop IPE 5.0: Patch for Performance Analyzer

    • You need the J2SE v1.3.0 for Solaris binary release to bootstrap the build. Once the bootstrap SDK 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 installed the Java 2 SDK in /usr/j2se, you need to do this:
      setenv ALT_BOOTDIR /usr/j2se
      

    • You must set the ALT_HOTSPOT_CLIENT_PATH and ALT_HOTSPOT_SERVER_PATH environment variables to the directory containing the Java HotSpot Client VM and Java HotSpot Server VM binary and auxilary files (the libjvm.so, libjvm_g.so and Xusage.txt files), respectively.

      The Java Hotspot product must be built before the J2SE build. The new Hotspot binaries are used to complete the build of the J2SE source code. A bootstrap Hotspot directory must be assembled in preparation for the J2SE build. This is accomplished by creating the following directories and links:

      setenv ALT_HOTSPOT_CLIENT_PATH hotspot_client_bootstrap
      mkdir $ALT_HOTSPOT_CLIENT_PATH
      cd $ALT_HOTSPOT_CLIENT_PATH
      ln -s <scsl_home>/hotspot1.3.1/build/solaris/solaris_sparc_compiler1/jvmg/libjvm_g.so libjvm_g.so
      ln -s <scsl_home>/hotspot1.3.1/build/solaris/solaris_sparc_compiler1/product/libjvm.so libjvm.so
      ln -s <scsl_home>/hotspot1.3.1/src/share/vm/Xusage.txt Xusage.txt
      cd ..
      
      setenv ALT_HOTSPOT_SERVER_PATH hotspot_server_bootstrap
      mkdir $ALT_HOTSPOT_SERVER_PATH
      cd $ALT_HOTSPOT_SERVER_PATH
      ln -s <scsl_home>/hotspot1.3.1/build/solaris/solaris_sparc_compiler2/jvmg/libjvm_g.so libjvm_g.so
      ln -s <scsl_home>/hotspot1.3.1/build/solaris/solaris_sparc_compiler2/product/libjvm.so libjvm.so
      ln -s <scsl_home>/hotspot1.3.1/src/share/vm/Xusage.txt Xusage.txt
      cd ..
      
      The ALT_HOTSPOT_CLIENT_PATH and ALT_HOTSPOT_SERVER_PATH should be set to absolute directory path of Java Hotspot Client VM and Java HotSpot Server VM binary and auxilary files.

    • The build process uses the tools contained in the Solaris /usr/ccs/bin and /usr/bin directories. These directories and their contents are part of the standard developer or full installation of the Solaris operating environment. You should ensure that these directories are present and on your path. If these default locations for the Solaris tools are not valid on your build machine for some reason, you should specify your alternative locations for the tools by using the ALT_USRBIN_PATH and ALT_UNIXCCS_PATH environment variables.

    • 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/jdbc-odbc:
      setenv ALT_ODBCDIR /opt/jdbc-odbc
      
      You may also use ODBC 3.7 in place of ODBC2.11. You may download the Connect ODBC3.7 server from http://www.merant.com/products/datadirect/download/eval/connect_odbc/server.asp. Download the package labeled as being for Solaris. Run the script unixpi.ksh in the download bundle to install the ODBC 3.7 files. The installation script will ask you to choose which driver to install (dBase, DB2, FoxPro, etc.). Any choice will work for purposes of building the Java 2 SDK.

      The ODBC driver should be installed into the following directory structure. The structure should include the 2.11 directory even if you use ODBC 3.7 rather than ODBC 2.11.

        .../odbc/         Set ALT_ODBCDIR_PATH to this level.
              +- ISLIodbc/
                 +- 2.11/       
                    +- odbc files and directories (lib/, include/, etc.)
      

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

    • You will need Motif header files and runtime libraries (libXm). The J2SE build generates binaries for working with Motif versions 1.2 and 2.1. A Motif bootstrap area must be created which contains both versions of the header files and libraries. Use the ALT_MOTIF_DIR environment variable to point to absolute path of the Motif bootstrap area. The top level of the bootstrap directory must contain directories named motif12 and motif21, each of which must have subdirectories include and lib with contents as shown here:
               +- motif_bootstrap_area/  (set ALT_MOTIF_DIR to this level)
                  +- motif12/             
                  |  +- include/
                  |  |  +- Xm/  (from /usr/include/Xm on Solaris 2.6)
                  |  |     +- <many files>
                  |  |    
                  |  +- lib/    (from /usr/dt/lib/ on Solaris 2.6) 
                  |     +- libXm.so (symbolic link to libXm.so.3)
                  |     +- libXm.so.3
                  |                          
                  +- motif21/
                     +- include/
                     |  +- Xm/  (from /usr/include/Xm on Solaris 2.7)
                     |     +- <many files>
                     |    
                     +- lib/    (from /usr/dt/lib/ on Solaris 2.7) 
                        +- libXm.so (symbolic link to libXm.so.4)
                        +- libXm.so.4
                        +- sparcv9/    (64-bit Motif library)
                           +- libXm.so (symbolic link to libXm.so.4)
                           +- libXm.so.4
      
      In the example above, the name of the top-level directory is not important. It is not required to be named motif_bootstrap_area.


    If you are going to build the Java Plug-in product, you also need the following...
    • You need gcc version 2.95.2 built for the Solaris. Set the ALT_GCC_COMPILER_PATH environment variable to the directory containing the gcc binaries. Source code for gcc is available from http://www.gnu.org/software/gcc/.

    • You need to set up a bootstrap area containing the libraries and header files for the Mozilla browser. The libraries are part of the binary Mozilla downloads available at http://www.mozilla.org/releases/. Download the most recent release for Solaris SPARC and Intel. The .tar.gz files available for download may be labeled as being for Solaris 8. However, you can use these same libraries for building on Solaris 6. After untarring each of the bundles, you will see several .so files in the top-level directory and more .so files in the components subdirectory. Copy all of these .so files to the mozilla_libs directories of the bootstrap area as indicated in the diagram below. All the .so files in the mozilla_libs directory should be on the top level, with no subdirectories beneath mozilla_libs.

      To obtain the Mozilla header files, download the Mozilla source release from http://www.mozilla.org/build/unix-details.html. Follow the instructions on that web site to download and build Mozilla. When the build is finished, you will find the header files inside the dist/include directory. Copy these header files to the mozilla_headers directory of the bootstrap area as indicated in the diagram below.

    • You need to obtain the GLib and GTK+ files available from http://www.gtk.org/announce.html and add them to your bootstrap as shown below. GLib is part of the GTK+ v 1.2 Toolkit. Click on the ftp link near the bottom of the page named ftp://ftp.gtk.org/pub/gtk/v1.2/. From there you should be able to download the gtk+-1.2.8.tar.gz and glib-1.2.8.tar.gz packages.

      Use the following structure for the bootstrap area, with the ALT_DEVTOOLS_PATH environment variable set as indicated depending on whether you are building on Solaris Sparc or Solaris Intel. If you are building only on Sparc, you don't need to set up the i386 part of the bootstrap area. If you are building only on Solaris-Intel Architecture, you don't need to set up the sparc part of the bootstrap area.

          devtools       
             +- share/
             |   +- mozilla_headers/   # Mozilla header files
             |
             +- sparc                  # set ALT_DEVTOOLS_PATH here if building
             |   +- bin/               # on Solaris Sparc
             |   |   +- gnumake
             |   |
             |   +- plugin/
             |       +- libg/          # GLib components
             |       +- gtk/           # GTK+ components
             |       +- mozilla_libs/  # Mozilla libraries for Solaris Sparc
             |
             |
             +- i386                   # set ALT_DEVTOOLS_PATH here if building
                 +- bin/               # on Solaris Intel
                 |   +- gnumake
                 |
                 +- plugin/
                     +- libg/          # GLib components
                     +- gtk/           # GTK+ components
                     +- mozilla_libs/  # Mozilla libraries for Solaris Intel
                       
      
      


    Pre-build requirements for Microsoft Windows

    You need to perform the build on a Windows NT 4.0 platform with Service Pack 5. 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. Approximately 300 MB of free disk space is needed for the build.

    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 6.0 Professional edition with Service Pack 3 installed, for compiling C code. Though this software is required for compiling C code, the build is done using gnumake rather than with the Microsoft Visual C++ IDE.
      • MKS Toolkit version 6.1a (http://www.mks.com) for Unix emulation on the Windows NT platform.
      • The GNU Make tool (GNUMAKE.EXE) version 3.78.1, built for the MKS Shell per the instructions in the GNU Make 3.78.1 documentation.
      • ZIP.EXE and UNZIP.EXE should be installed in C:\UTILS. If you have them installed elsewhere, you must set the environment variable ALT_DEVTOOLS_PATH to their location. For example, if they are installed at D:\bin, you need to do this:
        set ALT_DEVTOOLS_PATH=D:\bin
        

      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.

      To prepare your system for the build, run the vcvars32.bat file from the Microsoft Visual C++ installation at C:\Program Files\Microsoft Visual Studio\VC98\BIN\vcvars32.bat. This file will set environment variables necessary for the build.

    • You need the J2SE v1.3.0 for Win32 binary release to bootstrap the build. After installing the bootstrap SDK, you need to set the ALT_BOOTDIR environment variable to point to its top-level directory. For example, if you've installed the Java 2 SDK 1.3.0 software in D:\java\jdk1.3, you need to do this from the DOS prompt:
      set ALT_BOOTDIR=D:\java\jdk1.3
      

    • You must set the ALT_HOTSPOT_CLIENT_PATH and ALT_HOTSPOT_SERVER_PATH environment variables to the location of the Java HotSpot Client VM and Java HotSpot Server VM binary and auxilary files (the jvm.dll, jvm_g.dll, and Xusage.txt files), respectively.

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

    Pre-build requirements for Linux

    You can build the Linux version of J2SE v1.3.1 on Red Hat Linux 6.1. Approximately 1.25 GB of free disk space is required for the build. You will also need to meet the following requirements.
    • You need GNU make 3.78.1 or later on your path.

    • You need the J2SE v1.3.0 for Linux binary release to bootstrap the build of the source code. Set the ALT_BOOTDIR environment variable to the path of your bootstrap SDK. For example, if you installed J2SE v1.3.0 at /usr/java/jdk1.3, then your gnumake command invocation should include the directive ALT_BOOTDIR=/usr/java/jdk1.3.

    • You must set the ALT_HOTSPOT_CLIENT_PATH and ALT_HOTSPOT_SERVER_PATH environment variables to the location of the Java HotSpot Client VM and Java HotSpot Server VM binary and auxilary files (the libjvm.so, libjvm_g.so, and Xusage.txt files), respectively.

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

    • You will need Motif header files and runtime libraries (libXm). A Motif bootstrap area must be created which contains the Motif header files and libraries. Use the ALT_MOTIF_DIR environment variable to point to the Motif bootstrap area. The bootstrap directory must have subdirectories named include and lib:
               +- motif_bootstrap_area/  Set ALT_MOTIF_DIR to this directory.
                  +- include/
                  +- lib/    
      
      The name of the top-level directory is not important. It does not have to be motif_bootstrap_area. The Motif include and lib directories are often under /usr/X11R6 on Linux systems. If you do not already have a Motif library on your Linux system, we recommend that you obtain the Motif library from http://www.openmotif.org. You will need both the runtime and developer packages from this site.

    • You will need the JDBC-ODBC Bridge driver for building the JDBC-ODBC packages. Use ODBC 3.7 in place of ODBC2.11. You may download the Connect ODBC3.7 server from http://www.merant.com/products/datadirect/download/eval/connect_odbc/server.asp. Download the package labeled as being for Solaris. Run the script unixpi.ksh in the download bundle to install the ODBC 3.7 files. The installation script will ask you to choose which driver to install (dBase, DB2, FoxPro, etc.). Any choice will work for purposes of building the Java 2 SDK.

      The ODBC driver should be installed into the following directory structure. Set the ALT_ODBCDIR_PATH environment variable as shown. The structure should include the 2.11 directory even though the files come from ODBC 3.7 rather than ODBC 2.11.

      .../odbc/         Set ALT_ODBCDIR_PATH to this level.
            +- ISLIodbc/
                +- 2.11/       
                    +- odbc files and directories (lib/, include/, etc.)
      


      If you are going to build the Java Plug-in product, you also need the following...

      • You need to set up a bootstrap area containing the libraries and header files for the Mozilla browser. The libraries are part of the binary Mozilla downloads available at http://www.mozilla.org/releases/. Download the most recent release for Linux. After installing the bundle, you will see several .so files in the top-level directory and more .so files in the components subdirectory. Copy all of these .so files to the mozilla_libs directory of the bootstrap area as indicated in the diagram below. All the .so files in the mozilla_libs directory should be on the top level, with no subdirectories beneath mozilla_libs.

        To obtain the Mozilla header files, download the Mozilla source release from http://www.mozilla.org/build/unix-details.html. Follow the instructions on that web site to download and build Mozilla. When the build is finished, you will find the header files inside the dist/include directory. Copy these header files to the mozilla_headers directory of the bootstrap area as indicated in the diagram below.

      • You need to obtain the GLib and GTK+ files available from http://www.gtk.org/announce.html and add them to your bootstrap as shown below. GLib is part of the GTK+ v 1.2 Toolkit. Click on the ftp link near the bottom of the page named ftp://ftp.gtk.org/pub/gtk/v1.2/. From there you should be able to download the gtk+-1.2.8.tar.gz and glib-1.2.8.tar.gz packages.

        Use the following structure for the bootstrap area, with the ALT_DEVTOOLS_PATH environment variable set as indicated.

            devtools       
               +- share/
               |   +- mozilla_headers/   # Mozilla header files
               |
               |
               +- linux                  # set ALT_DEVTOOLS_PATH here
                   +- bin/   
                   |   +- gnumake
                   |
                   +- plugin/
                       +- libg/          # GLib components
                       +- gtk/           # GTK+ components
                       +- mozilla_libs/  # Mozilla libraries for linux
                         
        
        


    Starting the Build

    Once you've met the pre-build requirements, you can start the build with a few simple steps.
    1. Change to the make directory of the community source release.

    2. On Solaris and Linux platforms, launch the build process by running this command:
      gnumake all plugin
      
      This will build both the Java 2 SDK and the Java Plug-in product.

      Source code for the Java Plug-in is not provided for Microsoft Windows platforms. On Microsoft Windows, launch the build process with this command:

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

    The build creates the binary files and auxilary resources of the Java 2 SDK and puts them in a newly created ../build/<platform> directory. Here, <platform> stands for solaris-sparc, solaris-i386, win32, or linux-i386.

    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 the following command from the make directory:

    On Solaris and Linux:
    gnumake plugin-clobber clobber
    
    On Microsoft Windows:
    gnumake clobber
    

    Quick-tesing the Build

    To do a quick test that the build has succeeded, add the build/<platform>/bin directory to the front of your path. (On Solaris and Linux systems, you can run the which java command to ensure that the newly created java executable will be executed.) Then run the java -version command. You should see output something like this:
    java version "1.3.1-internal"
    Java(TM) 2 Runtime Environment, Standard Edition (build 1.3.1-internal--010130-15:34)
    Java HotSpot(TM) Client VM (build 1.3.1-internal, mixed mode)
    
    Next, go to the demos directory and try running some of the demos. For example:
    cd build/<platform>/demo/jfc/SwingSet2
    java -jar SwingSet2.jar
    


    Troubleshooting Build Problems

    A build can fail for any number of reasons. Most failures are a result trying to build in an environment in which all the pre-build requirements have not been met. The first step in troubleshooting a build failure is to recheck that you have satisfied all the pre-build requirements for your platform.

    Some of the more common problems with builds are briefly descibed below, with suggestions for remedies.

    Troubleshooting the Java HotSpot VM Build

    Here are some errors that can occur during a build of the Java HotSpot VMs, and suggestions for how to get around the error. As with most build problems, the errors described here are due to not having all pre-build requirements met.
    • Can't find the ODBC library -- Use the ALT_ODBCDIR environment variable to point to the location of the appropriate ODBC library (ISLIodbc 2.11).

    • Error message: __Cimpl::cplus_init is an undefined symbol -- This indicates that you don't have the patched C++ 5.0 compiler. Make sure you have the required patches for the compiler installed.

    • Error message: Fatal error. Cannot locate JDK installation -- You need to set the JAVA_HOME environment variable to the location of an installation of J2SE v1.3.0 or J2SE v1.3.1 (binary releases).

    • Error message: There was an error trying to initialize the HPI library -- You need a libhpi.so library in the J2SE binary installation specified by your JAVA_HOME environment variable. The library should be at $JAVA_HOME/jre/lib/<arch>/native_threads/libhpi.so.

    • If your build machine seems to be overloaded from too many simultaneous C++ compiles, try setting the HOTSPOT_BUILD_JOBS environment variable to 1 (or, if you're using a multiple CPU machine, set it to the largest integer that is less than or equal to 1.5 times the number of CPUs).

    • Error message: don't know how to make 'os_share_win32.hpp' -- File os_share_win32.hpp, located at src\os\share\win32\vm in the Java HotSpot source tree, is a zero-length empty file. This file is empty intentionally, and it must be present in order for the build on Windows NT to work. However, some zip utilities such as WinZip 8.0 will not extract zero-length files. You should check to ensure that the zip utility you used to unpack the source bundle extracted this file. If you do not see this file in your distribution, you should create a zero-length, empty file at src\os\share\win32\vm\os_share_win32.hpp.

    Troubleshooting the Java 2 SDK Build

    If you can't determine what's causing a build 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 variables set.

    For example, here are a couple error messages that you might see if you haven't met the pre-build requirements.

    • Error message: Your Microsoft Visual C++ compiler predates the 6.0 release -- (Win32 only) To do a build on a Win32 system, you must use version 6.0 of Microsoft Visual C++ with Service Pack 3 (not Service Pack 4). If you have version 6 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.

    • A failure in make/java/redist -- This part of the build is used to copy the Java HotSpot VM binaries over to the Java 2 SDK build. The build will fail if it cannot find the Java HotSpot VM binaries. Check that the ALT_HOTSPOT_CLIENT_PATH and ALT_HOTSPOT_SERVER_PATH environment variables are set to the correct location of the Java HotSpot Client VM and Java HotSpot Server VM binaries respectively.

    Building Other Targets

    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 make subdirectory inside the j2sdk1.3.1 directory of your community source installation and and run this command:
    gnumake <target1> <target2> ...
    Here, <target1>, <target2>, etc. stand for all or any other target described in the following list. Note that the target order is important. You must use the following order when building and optionally clobbering:
    gnumake [clobber] all [plugin-clobber] [plugin] [docs] images
    
    all
    This is the target for building the full Java 2 SDK, including the auxilary libraries for internationalization support and the Java Platform Debugger Interface product.
    plugin
    This target builds the Java Plug-in product. This target is available for Solaris and Linux only. The all target must be run prior to running the plugin target.
    clobber
    This target deletes all files generated during previous Java 2 SDK builds.
    plugin-clobber
    This target deletes all files generated during previous builds of the Java Plug-in product.
    docs
    This target builds the API documentation using the Java doc tool. The all target must be run prior to running the docs target.
    images
    This target will produce tar archives of the Java 2 SDK. The all target must be run prior to the images target.

    Copyright © 2001 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, CA 94303-4900 USA. All rights reserved.