README.linux.src for JDK 1.2, Version pre-release2
Steve Byrne  java-linux@java.blackdown.org
6/2/1999

Building The Linux JDK From Source
==================================

This note describes the process that you need to go through to build the 
JDK from the source distribution.  Please read through them all before
starting to build.


1) Obtain the JDK Source 
------------------------

The Sun Java Development Kit (JDK) source code is a product that's licensed
from Sun Microsystems, Inc. to people interested in using it for non-commercial
purposes and for porting it to new platforms (that's people like you) under the
terms of the Sun Community Source License.  You will need to go to
http://www.sun.com/software/communitysource/java2 and follow the links leading
towards licensing of the source to the JDK.

Fill out the license information and send it in.  Within a short amount of time
(typically a few days, currently), you'll get an email message telling you
how and where to retrieve the sources from.  The particular information 
you are given is only valid for a short amount of time, so you need to 
promptly retrieve the source distribution once you have the information.


2) Preparing the Build Environment
----------------------------------

You'll need to have sufficient disk space, sufficient memory (virtual or
real), and both an existing JDK binary distribution (JRE is not enough) and
GCC.  Let's look at what "sufficient" means for each of these.

Disk space.  I just did a "du" on my source and build directory containing the
complete sources and results of the build.  A little over 226 meg.  
Although it seems large, that's less than $5 worth of disk space at current
prices.  

Memory (RAM).  I typically build on a 300Mhz/64M RAM system, and I have a
generous 128M swap area that seems to be sufficient.  As much RAM as you can
get will help a lot.

On my system builds typically take about 2 hours. 

JDK.  This for bootstrapping the system.  You'll need the Java 2 (JDK 1.2) 
port from Blackdown; see http://www.blackdown.org.

egcs (gcc).  You'll need it.  You'll need a recent version, like 2.1.60.
Debian 2.1 and RedHat 6.0 both include this as an option.  When the grand gcc
unification occurs later this summer, you should just be able to use that.

Motif.  You can build the Linux JDK with either Motif or LessTif.  If you want
to use Motif, you need to get a copy of 2.x.  You can get CDs from a variety of
distributors; the Blackdown team uses MetroLink.  Make sure you set it up in a
standard place like /usr/X11R6/.  Or, you can get LessTif from
http://www.lesstif.org (it'll point you to where the current version is).  We
recommend that you get at least version 0.88 to do your build with.  Build
LessTif according to its instructions, and set the ALT_MOTIF_DIR variable on
the "make" command line to be where you have LessTif installed (i.e. the
directory that contains the LessTif bin, lib, and include directories).  You
can also set an environment variable called ALT_MOTIF_DIR in the same manner,
and then you won't have to specify it on the "make" command line each time you
build the JDK.  Note that we don't have a huge amount of experience building
Linux Java 2 with LessTif, so you may find that it does not work (on the other
hand, you may find that it works well -- either way, we'd be happy to hear
about your experiences).

3) Get the diffs
----------------

The stock JDK source distribution from Sun won't build on Linux.  You'll need
to apply a patch (a set of diffs) to it before you can build.  

Follow the Linux Java port links at http://www.blackdown.org to obtain the
diffs for the the Linux Java 2 port.   They're relatively small (~155 k
compressed). 

4) Get patch-o-matic
--------------------

This is a new shell script that I cooked up to make the patching easier.
To use it, you need to define 4 environment variables (or hack the script
at the top):

JDK_DIFFS_FILE		This gives the full path to the gzipped 1.2 diffs file
			that you can find with the port binaries (you did
			remember to get this, didn't you?)

JDK_BOOT_DIR		This gives the full, absolute path to where you've
			unpacked the bootstrap Linux Java 2 binary release.
			$JDK_BOOT_DIR/bin should contain "java" (and other
			programs like "rmic") if you have defined it correctly.

JDK_TARGET_DIR		This defines where you want your patched version of
			the world to end up.  It should either name a directory
			that does not yet exist, or should name a directory
			which exists but is empty.  

JDK_SRC_ZIP_FILE	This provides the full path to the original Solaris
			Java 2 sources from Sun .zip file. 

When you've got all of these defined, just run patch-o-matic (you did remember
to chmod +x it, of course), and watch the fun.  Be sure that the target
directory that you've defined has at least 300 meg free.

5) Do the build!
----------------

cd into "build/linux" in the target directory and type: 

    make build_release

.
Then type: 

    build_release

(if your egcc compiler isn't called "gcc", you need to
do "build_release CC=egcc CXX=egcc"; you can specify the exact path to the egcc
binary instead of just it's name if your egcc isn't in $PATH.  As an
alternative, you can set the JCK_EGCC to be the name of the egcc compiler; it
can be either just "egcc" if that's in your PATH, or the full path to the
executable if not).

Sit back.  Read a book.  Start looking at the source code.  Figure out how
*you'd* add Socks V5 support to the JDK.  

The build will take a while.  On my 300 Mhz @ home, it would take about
2 hours or a little more.  There will be times when it seems to
be doing nothing, especially when compiling a lot of Java files.  I suggest
renting a good video and watching it while your build proceeds.  By the time
you find out who Keyser Soze really is, you've built a new JDK 1.2 of your very
own!

By default the build process will build both the debug and the optimized
versions of the runtime system; to build just one or the other say
"build_release debug" or "build_release optimized".

The resulting binaries live in the "bin" subdirectory of the "build/linux"
directory.  You can invoke them directly from there for instant "yes I've built
it and it works, DAMN I'm good!"  gratification.  Yippee!!!

To completely erase the products of a build in preparation for doing a fresh
build, do "build_release clobber".  

That's it!  
