diff -r 000000000000 -r fd16c54261b3 README-builds.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/README-builds.html Sat Dec 01 00:00:00 2007 +0000 @@ -0,0 +1,1452 @@ + + + +OpenJDK Build README + + +
+ +
+

OpenJDK Build README

+
+ + +
+ +

Introduction

+ +
+

+ This README file contains build instructions for the + OpenJDK. + Building the source code for the + OpenJDK + requires + a certain degree of technical expertise. +

+ + +
+ +

Contents

+ +
+ +
+ + +
+ +

Minimum Build Environments

+ +
+

+ This file often describes specific requirements for what we call the + "minimum build environments" (MBE) for the JDK. + Building with the MBE will generate the most compatible + bits that install on, and run correctly on, the most variations + of the same base OS and hardware architecture. + These usually represent what is often called the + least common denominator platforms. + It is understood that most developers will NOT be using these + specific platforms, and in fact creating these specific platforms + may be difficult due to the age of some of this software. +

+ +

+ The minimum OS and C/C++ compiler versions needed for building the + OpenJDK: +

+

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Base OS and ArchitectureOSCompiler
Linux X86 (32bit)Red Hat Enterprise Linux 4 gcc 4
Linux X64 (64bit)Red Hat Enterprise Linux 4 gcc 4
Solaris SPARC (32bit)Solaris 10 + patches +
+ See SunSolve for patch downloads. + 		Sun Studio 11
Solaris SPARCV9 (64bit)Solaris 10 + patches +
+ See SunSolve for patch downloads. + 		Sun Studio 11
Solaris X86 (32bit)Solaris 10 + patches +
+ See SunSolve for patch downloads. + 		Sun Studio 11
Solaris X64 (64bit)Solaris 10 + patches +
+ See SunSolve for patch downloads. + 		Sun Studio 11
Windows X86 (32bit)Windows XPMicrosoft Visual Studio .NET 2003 Professional
Windows X64 (64bit)Windows Server 2003 - Enterprise x64 EditionMicrosoft Platform SDK - April 2005
+
+
+ + +
+ +

Specific Developer Build Environments

+ +
+

+ We won't be listing all the possible environments, but + we will try to provide what information we have available to us. +

+ +

Fedora

+ +
+ TBD +
+ +

Debian

+ +
+ TBD +
+ +

Ubuntu

+ +
+

+ In addition to needing the Bootstrap JDK and the Binary Plugs, + when building on Ubuntu you will need to + make sure certain packages are installed. + In particular, certain X11 packages, make, m4, gawk, gcc 4, + binutils, cups, freetype + and alsa. + +

Ubuntu 6.06

+ +

+ The following list of packages for Ubuntu 6.06 is a working set that + does appear to work. + +

+ Note that it's quite possible that some of these + packages are not required, so anyone discovering that some of the + packages listed below are NOT required, + please let the + OpenJDK + team know. +

+ All the packages below can be installed with the + Synaptic Package manager provided with the base Ubuntu 6.06 release. + +

+ +
+ +

Ubuntu 7.04

+ +

+ Using the Synaptic Package Manager, download the following + packages (double indented packages are automatically aquired + due to package dependencies): + +

+ +
+
+ + +
+ +

Source Directory Structure

+ +
+

+ The source code for the + OpenJDK is + delivered in 3 sibling directories: + hotspot, + langtools, + corba, + jaxws, + jaxp, + jdk + and + The hotspot directory contains the source code and make + files for + building the + OpenJDK + Hotspot Virtual Machine. + The jdk + directory contains the source code and make files for + building the + OpenJDK + runtime libraries, tools and demos. + The top level Makefile is used to build the complete OpenJDK + release including building the hotspot + VM, staging the VM binaries, and building the + OpenJDK + runtime libraries, + tools and demos. +

+ + +
+ +

Build Information

+ +
+

+ Building the + OpenJDK + is done with a gmake + command line and various + environment or make variable settings that direct the make rules + to where various components have been installed. + Where possible the makefiles will attempt to located the various + components in the default locations or any component specific + variable settings. + When the normal defaults fail or components cannot be found, + the various + ALT_* variables (alternates) + can be used to help the makefiles locate components. +

+ Refer to the bash/sh/ksh setup file + jdk/make/jdk_generic_profile.sh + if you need help in setting up your environment variables. + A build could be as simple as: +

+ 

+                bash
+                . jdk/make/jdk_generic_profile.sh
+                gmake sanity && gmake
+
+
+

+ Of course ksh or sh would work too. + But some customization will probably be necessary. + The sanity rule will make some basic checks on build + dependencies and generate appropriate warning messages + regarding missing, out of date, or newer than expected components + found on your system. +

+ + +
+ +

GNU make (gmake)

+ +
+

+ The Makefiles in the + OpenJDK + are only valid when used with the + GNU version of the utility command make + (gmake). + A few notes about using GNU make: +

+

+ Information on GNU make, and access to ftp download sites, are + available on the + + GNU make web site + . + The latest source to GNU make is available at + ftp.gnu.org/pub/gnu/make/. +

+ + +
+ +

Basic Linux System Setup

+ +
+

+ i586 only: + The minimum recommended hardware for building the Linux version + is a Pentium class processor or better, at least 256 MB of RAM, and + approximately 1.5 GB of free disk space. +

+ X64 only: + The minimum recommended hardware for building the Linux + version is an AMD Opteron class processor, at least 512 MB of RAM, and + approximately 4 GB of free disk space. +

+ The build will use the tools contained in + /bin and + /usr/bin + of a standard installation of the Linux operating environment. + You should ensure that these directories are in your + PATH. +

+ Note that some Linux systems have a habit of pre-populating + your environment variables for you, for example JAVA_HOME + might get pre-defined for you to refer to the JDK installed on + your Linux system. + You will need to unset JAVA_HOME. + It's a good idea to run env and verify the + environment variables you are getting from the default system + settings make sense for building the + OpenJDK. +

+ + + +

Basic Linux Check List

+ +
+
    +
  1. + Install the + Bootstrap JDK, set + ALT_BOOTDIR. +
    2. +
  2. + Install the + Binary Plugs, set + ALT_BINARY_PLUGS_PATH. +
    3. +
  3. + Install or upgrade the FreeType development + package. +
    4. +
+
+ + +
+ +

Basic Solaris System Setup

+ +
+

+ The minimum recommended hardware for building the + Solaris SPARC version is an UltraSPARC with 512 MB of RAM. + For building + the Solaris x86 version, a Pentium class processor or better and at + least 128 MB of RAM are recommended. + Approximately 1.4 GB of free disk + space is needed for a 32-bit build. +

+ If you are building the 64bit version, you should + run the command "isainfo -v" to verify that you have a + 64-bit installation. + An additional 7 GB of free disk space is needed + for a 64-bit build. +

+ The build uses the tools contained in /usr/ccs/bin + and /usr/bin of a standard developer or full installation of + the Solaris operating environment. +

+ + + +

Basic Solaris Check List

+ +
+
    +
  1. + Install the + Bootstrap JDK, set + ALT_BOOTDIR. +
    2. +
  2. + Install the + Binary Plugs, set + ALT_BINARY_PLUGS_PATH. +
    3. +
  3. + Install the + Sun Studio Compilers, set + ALT_COMPILER_PATH. +
    4. +
  4. + Install the + CUPS Include files, set + ALT_CUPS_HEADERS_PATH. +
    5. +
+
+ + +
+ +

Basic Windows System Setup

+ +
+

+ i586 only: + The minimum recommended hardware for building the 32bit or X86 + Windows version is an Pentium class processor or better, at least + 512 MB of RAM, and approximately 600 MB of free disk space. + + NOTE: The Windows 2000 build machines need to use the + file system NTFS. + Build machines formatted to FAT32 will not work + because FAT32 doesn't support case-sensitivity in file names. + +

+ X64 only: + The minimum recommended hardware for building + the Windows X64 version is an AMD Opteron class processor, at least 1 + GB of RAM, and approximately 10 GB of free disk space. +

+ + + +

Windows Paths

+ +
+

+ Windows: + Note that GNU make is a historic utility and is based very + heavily on shell scripting, so it does not tolerate the Windows habit + of having spaces in pathnames or the use of the \characters in pathnames. + Luckily on most Windows systems, you can use /instead of \, and + there is always a 'short' pathname without spaces for any path that + contains spaces. + Unfortunately, this short pathname can be somewhat dynamic and the + formula is difficult to explain. + You can use cygpath utility to map pathnames with spaces + or the \character into the C:/ style of pathname + (called 'mixed'), e.g. + cygpath -s -m "path". +

+ The makefiles will try to translate any pathnames supplied + to it into the C:/ style automatically. +

+ Note that use of CYGWIN creates a unique problem with regards to + setting PATH. Normally on Windows + the PATH variable contains directories + separated with the ";" character (Solaris and Linux uses ":"). + With CYGWIN, it uses ":", but that means that paths like "C:/path" + cannot be placed in the CYGWIN version of PATH and + instead CYGWIN uses something like /cygdrive/c/path + which CYGWIN understands, but only CYGWIN understands. + So be careful with paths on Windows. +

+ + + +

Basic Windows Check List

+ +
+
    +
  1. + Install the + CYGWIN product. +
    2. +
  2. + Install the + Bootstrap JDK, set + ALT_BOOTDIR. +
    3. +
  3. + Install the + Binary Plugs, set + ALT_BINARY_PLUGS_PATH.. +
    4. +
  4. + Install the + Microsoft Visual Studio .NET 2003 Professional or the + Microsoft Platform SDK. +
    5. +
  5. + Setup all environment variables for compilers + (see compilers). +
    6. +
  6. + Install + Microsoft DirectX SDK. +
    7. +
+
+ + +
+ +

Build Dependencies

+ +
+

+ Depending on the platform, the + OpenJDK + build process has some basic + dependencies on components not part of the + OpenJDK + sources. + Some of these are specific to a platform, some even specific to + an architecture. + Each dependency will have a set of ALT variables that can be set + to tell the makefiles where to locate the component. + In most cases setting these ALT variables may not be necessary + and the makefiles will find defaults on the system in standard + install locations or through component specific variables. + +

Bootstrap JDK

+ +
+

+ All + OpenJDK + builds require access to the previously released + JDK 6, this is often called a bootstrap JDK. + The JDK 6 binaries can be downloaded from Sun's + JDK 6 download site. + For build performance reasons + is very important that this bootstrap JDK be made available on the + local disk of the machine doing the build. + You should always set + ALT_BOOTDIR + to point to the location of + the bootstrap JDK installation, this is the directory pathname + that contains a bin, lib, and include + It's also a good idea to also place its bin directory + in the PATH environment variable, although it's + not required. +

+ Solaris: + Some pre-installed JDK images may be available to you in the + directory /usr/jdk/instances. + If you don't set + ALT_BOOTDIR + the makefiles will look in that location for a JDK it can use. +

+ +

Binary Plugs

+ +
+

+ Not all of the source code that makes up the JDK is available + under an open-source license. + In order to build an OpenJDK binary from source code, + you must first download and install the appropriate + binary plug bundles from the OpenJDK Download area. + During the OpenJDK build process these "binary plugs" + for the encumbered components will be copied into your + resulting OpenJDK binary build image. + These binary plug files are only for the purpose of + building an OpenJDK binary. + Download the Binary Plugs by selecting the Downloads + link at + the OpenJDK site, + install the bundle, + and make sure you set + ALT_BINARY_PLUGS_PATH + to the root of this installation. +

+ +

Certificate Authority File (cacert)

+ +
+

+ See + www.wikipedia.org/wiki/CAcert + for a better understanding of the Certificate Authority (CA). + A certificates file named "cacerts" + represents a system-wide keystore with CA certificates. + In JDK and JRE + binary bundles, the "cacerts" file contains root CA certificates from + several public CAs (e.g., VeriSign, Thawte, and Baltimore). + The source contain a cacerts file + without CA root certificates. + Formal JDK builders will need to secure + permission from each public CA and include the certificates into their + own custom cacerts file. + Failure to provide a populated cacerts file + will result in verification errors of a certificate chain during runtime. + The variable + ALT_CACERTS_FILE + can be used to override the default location of the + cacerts file that will get placed in your build. + By default an empty cacerts file is provided and that should be + fine for most JDK developers. +

+ +

Compilers

+ +
+ + + Linux gcc/binutils + + +
+

+ The GNU gcc compiler version should be 3.2.2 or newer. + The binutils package should be 2.11.93.0.2-11 or newer. + The compiler used should be the default compiler installed + in /usr/bin. +

+ + Solaris: Sun Studio + +
+

+ At a minimum, the + + Sun Studio 11 Compilers + (containing version 5.8 of the C and C++ compilers) is required, + with patches from the + + SunSolve web site. +

+ Set + ALT_COMPILER_PATH + to point to the location of + the compiler binaries, and place this location in the PATH. +

+ The Sun Studio Express compilers at: + + Sun Studio Express Download site + are also an option, although these compilers have not + been extensively used yet. +

+ + + Windows i586: Microsoft Visual Studio .NET 2003 Professional + + +
+

+ The 32-bit + OpenJDK + Windows build + requires Microsoft Visual Studio .NET 2003 (VS2003) Professional + Edition compiler. + The compiler and other tools are expected to reside + in the location defined by the variable VS71COMNTOOLS which + is set by the Microsoft Visual Studio .NET installer. +

+ Once the compiler is installed, + it is recommended that you run VCVARS32.BAT + to set the compiler environment variables + MSVCDIR, + INCLUDE, + LIB, and + PATH + prior to building the + OpenJDK. + The above environment variables MUST be set. +

+ The Microsoft Visual Studio .NET 2005 (VS2005) compiler + will not work at this time due to the new runtime dll + and the manifest requirements. +

+ + + Windows X64: Microsoft Platform SDK April 2005 + + +
+

+ On X64, + the Microsoft Platform Software + Development Kit (SDK), April 2005 Edition compiler, is required for + building the + OpenJDK + because it contains the C/C++ compiler. + You will need to minimally install the Core SDK and + the MDAC SDK features of this compiler. +

+ Once the Platform SDK is installed, + it is recommended that you run SetEnv.Cmd /X64 + to set the compiler environment variables + MSSDK, + MSTOOLS, + INCLUDE, + LIB, and + PATH + prior to building the + OpenJDK. + The above environment variables MUST be set. +

+ Note that this compiler may say it's version is a + Microsoft Visual Studio .NET 2005 (VS2005), but be careful, + it will not match the official VS2005 product. + This Platform SDK compiler is only used on X64 builds. +

+ +
+ +

Common UNIX Printing System (CUPS) Headers (Solaris & Linux)

+ +
+

+ Solaris: + CUPS header files are required for building the + OpenJDK on Solaris. + The Solaris header files can be obtained by installing + the package SFWcups from the Solaris Software + Companion CD/DVD, these often will be installed into + /opt/sfw/cups. +

+ Linux: + CUPS header files are required for building the + OpenJDK on Linux. + The Linux header files are usually available from a "cups" + development package, it's recommended that you try and use + the package provided by the particular version of Linux that + you are using. +

+ The CUPS header files can always be downloaded from + www.cups.org. + The variable + ALT_CUPS_HEADERS_PATH + can be used to override the default location of the + CUPS Header files. +

+ +

FreeType 2

+ +
+

+ Version 2.3 or newer of FreeType is required for building the OpenJDK. + On Unix systems required files can be available as part of your + distribution (while you still may need to upgrade them). + Note that you need development version of package that + includes both FreeType library and header files. +

+

+ You can always download latest FreeType version from the + FreeType website. +

+

+ Makefiles will try to pick FreeType from /usr/lib and /usr/include. + In case it is installed elsewhere you will need to set environment + variables + ALT_FREETYPE_LIB_PATH + and + ALT_FREETYPE_HEADERS_PATH + to refer to place where library and header files are installed. +

+
+ +

Advanced Linux Sound Architecture (ALSA) (Linux only)

+ +
+

+ Linux only: + Version 0.9.1 or newer of the ALSA files are + required for building the + OpenJDK on Linux. + These Linux files are usually available from an "alsa" + of "libasound" + development package, it's recommended that you try and use + the package provided by the particular version of Linux that + you are using. + The makefiles will check this emit a sanity error if it is + missing or the wrong version. + As a last resort you can go to the + + Advanced Linux Sound Architecture Site. +

+ +

Windows Specific Dependencies

+ +
+ + Unix Command Tools (CYGWIN) + +
+

+ The + OpenJDK + requires access to a set of unix command tools + on Windows which can be supplied by + CYGWIN. +

+ The + OpenJDK + build + requires CYGWIN version 1.5.12 or newer. + Information about CYGWIN can + be obtained from the CYGWIN website at + www.cygwin.com. +

+ By default CYGWIN doesn't install all the tools required for building + the OpenJDK. + Along with the default installation, you need to install + the following tools. +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Binary NamePackageDescription
ar.exeDevelbinutils: The GNU assembler, linker and binary + utilities
make.exeDevelmake: The GNU version of the 'make' utility
m4.exeInterpretersm4: GNU implementation of the traditional Unix macro + processor
cpio.exeUtilscpio: A program to manage archives of files
file.exeUtilsfile: Determines file type using 'magic' numbers
+
+
+ + + Microsoft DirectX 9.0 SDK header files and libraries + + +
+

+ Microsoft DirectX 9.0 SDK (Summer 2004) + headers are required for building + OpenJDK. + This SDK can be downloaded from + + Microsoft DirectX 9.0 SDK (Summer 2004). + If the link above becomes obsolete, the SDK can be found from + the Microsoft Download Site + (search with "DirectX 9.0 SDK Update Summer 2004"). + The location of this SDK can be set with + ALT_DXSDK_PATH + but it's normally found via the DirectX environment variable + DXSDK_DIR. +

+ + + MSVCRT.DLL + + +
+

+ i586 only: + The + OpenJDK + 32bit build requires + access to MSVCRT.DLL + version 6.00.8337.0 or newer. + If the MSVCRT.DLL is not installed in + the system32 directory set the + ALT_MSVCRT_DLL_PATH + variable to the location. +

+ X64 only: + The OpenJDK 64bit build requires access to + MSVCRT.DLL version 7.0.3790.0 or newer, which is + usually supplied by the + Platform SDK. + If it is not available from the Platform SDK, + set the + ALT_MSVCRT_DLL_PATH + variable to the location. +

+ + + MSVCR71.DLL + + +
+

+ i586 only: + The + OpenJDK + build requires access to + MSVCR71.DLL version 7.10.3052.4 or newer which should be + supplied by the + Visual Studio product + If the MSVCR71.DLL is not available from the + Visual Studio product + set the + ALT_MSVCR71_DLL_PATH + variable to the location. +

+ +
+ + +
+ + +
+ +

Creating the Build

+ +
+

+ Once a machine is setup to build the + OpenJDK, + the steps to create the + build are fairly simple. + The various ALT settings can either be made into variables + or can be supplied on the + gmake + command. +

+

    +
  1. Use the sanity rule to double check all the ALT settings: +
    + + gmake + sanity + [ARCH_DATA_MODEL=32 or 64] + [other "ALT_" overrides] + +
    +
    2. +
  2. Start the build with the command: +
    + + gmake + [ARCH_DATA_MODEL=32 or 64] + [ALT_OUTPUTDIR=output_directory] + [other "ALT_" overrides] + +
    +
    3. +
+

+ Solaris: + Note that ARCH_DATA_MODEL is really only needed on Solaris to + indicate you want to built the 64-bit version. + And before the Solaris 64-bit binaries can be used, they + must be merged with the binaries from a separate 32-bit build. + The merged binaries may then be used in either 32-bit or 64-bit mode, with + the selection occurring at runtime + with the -d32 or -d64 options. +

+ + +
+ +

Testing the Build

+ +
+

+ When the build is completed, you should see the generated + binaries and associated files in the j2sdk-image + directory in the output directory. + The default output directory is + build/platform, + where platform is one of +

+ In particular, the + build/platform/j2sdk-image/bin + directory should contain executables for the + OpenJDK + tools and utilities. +

+ You can test that the build completed properly by using the build + to run the various demos that you will find in the + build/platform/j2sdk-image/demo + directory. +

+ The provided regression tests can be run with the jtreg + utility from + the jtreg site. +

+ + +
+ +

Environment/Make Variables

+ +

+Some of the +environment or make variables (just called variables in this +document) that can impact the build are: + +

+ +
+ +
PATH
+
Typically you want to set the PATH to include: +
    +
  • The location of the GNU make binary
    • +
  • The location of the JDK 6 java + (see Bootstrap JDK)
    • +
  • The location of the C/C++ compilers + (see compilers)
    • +
  • The location or locations for the Unix command utilities + (e.g. /usr/bin)
    • +
+
+ +
ARCH_DATA_MODEL
+
The ARCH_DATA_MODEL variable + is used to specify whether the build is to generate 32-bit or 64-bit + binaries. + The Solaris build supports either 32-bit or 64-bit builds, but + Windows and Linux will support only one, depending on the specific + OS being used. + Normally, setting this variable is only necessary on Solaris. + Set ARCH_DATA_MODEL to 32 for generating 32-bit binaries, + or to 64 for generating 64-bit binaries. +
+ +
ALT_BOOTDIR
+
+ The location of the bootstrap JDK installation. + See Bootstrap JDK for more information. + You should always install your own local Bootstrap JDK and + always set ALT_BOOTDIR explicitly. +
+ +
ALT_OUTPUTDIR
+
+ An override for specifying the (absolute) path of where the + build output is to go. + The default output directory will be build/platform. +
+ +
ALT_COMPILER_PATH
+
+ The location of the C/C++ compiler. + The default varies depending on the platform. +
+ +
ALT_CACERTS_FILE
+
+ The location of the cacerts file. + The default will refer to + jdk/src/share/lib/security/cacerts. +
+ +
ALT_BINARY_PLUGS_PATH
+
+ The location of the binary plugs installation. + See Binary Plugs for more information. + You should always have a local copy of a + recent Binary Plugs install image + and set this variable to that location. +
+ +
ALT_CUPS_HEADERS_PATH
+
+ The location of the CUPS header files. + See CUPS information for more information. + If this path does not exist the fallback path is + /usr/include. +
+ + +
ALT_FREETYPE_LIB_PATH
+
+ The location of the FreeType shared library. + See FreeType information for details. +
+ +
ALT_FREETYPE_HEADERS_PATH
+
+ The location of the FreeType header files. + See FreeType information for details. +
+ +
Windows specific:
+
+
+
ALT_MSDEVTOOLS_PATH
+
+ The location of the Microsoft Visual Studio .NET 2003 + tools 'bin' directory. + The default is usually derived from + ALT_COMPILER_PATH. +
+ +
ALT_DXSDK_PATH
+
+ The location of the + Microsoft DirectX 9 SDK. + The default will be to try and use the DirectX environment + variable DXSDK_DIR, + failing that, look in C:/DXSDK. +
+ +
ALT_MSVCRT_DLL_PATH
+
+ The location of the + MSVCRT.DLL. +
+ +
ALT_MSVCR71_DLL_PATH
+
+ i586 only: + The location of the + MSVCR71.DLL. +
+
+
+ +
+
+ + +
+ +

Troubleshooting

+ +
+

+ A build can fail for any number of reasons. + Most failures + are a result of 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. + Look for the check list of the platform you are building on in the + Table of Contents. + +

+ You can validate your build environment by using the sanity + target. + Any errors listed + will stop the build from starting, and any warnings may result in + a flawed product build. + We strongly encourage you to evaluate every + sanity check warning and fix it if required, before you proceed + further with your build. + +

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

+
+ +