README.linux.src for JDK 1.1.8, Version 2
Steve Byrne/Juergen Kreileder (java-linux@java.blackdown.org)
May 25 2000

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).  You need to go to http://java.sun.com [if
someone has the real URL handy I'd be glad to update this] 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 build directory containing the
complete results of the build, including the a freshly built complete
JDK, JRE, RT, and I18N system.  A little over 158 meg.  Although it
seems large, that's less than $16 worth of disk space at current
prices.  You can get by with less; this is the upper bound.

Memory (RAM).  I've built the system with as little as 20M RAM (with X
running).  I don't recommend it, but it can be done.  The big issue is
having enough virtual and physical memory available during compilation
of some of the Java classes, particularly the I18N char to byte
converters.  I think that 90M of total available memory is sufficient
[please let me know if your mileage is different].  As much RAM as you
can get helps; you'll seriously thrash while building the I18N char
converters if you don't have enough (it'll still build, it'll just
take longer).

JDK.  This for bootstrapping the system.  You'll need something
recent.  See http://www.blackdown.org.  I recommend getting the Linux
JDK 1.1.8 binaries and installing them, although you can build with
the JDK 1.1.7 binaries (since you're reading this, you've probably
been smart enough to follow my advice and get the 1.1.7 binaries --
good choice!).  (BTW, I said "JRE isn't enough" and you may be
wondering why: JRE does not include the Java compiler; without that,
you can't build the Java compiler from the sources you've worked so
hard to obtain).

GCC.  You'll need it.  The exact version doesn't matter much, but get
a version that's known to be realiable (we use 2.95.2).

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.1.x (e.g. from
http://www.opengroup.org/openmotif/).  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.89.4 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.

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 JDK 1.1.8.  They're relatively small (~100 k
compressed).

4) Unpack the source distribution
---------------------------------

Untar the sources you obtained into the directory of your choosing.
You did remember to choose a directory on a file system with
sufficient space, didn't you?  Good.

5) Fix the sources
------------------

We're not doing a build for Solaris.  Some of the top level
directories in the JDK source tree that you've unpacked have "solaris"
in their names.  This will never do.

cd into the "build" directory.  Rename the "solaris" directory to be
"linux".  cd up and over into the "src" directory.  Rename that
"solaris" directory to also be called "linux".  cd back up to the top
directory (the one containing "build" and "src" as direct children).

6) Apply the diffs
------------------

Make sure you're in the top level directory of the source
distribution.  This directory should have "build" and "src" as
immediate child directories.

Do

   patch -NEp1 < jdk1.1.8v2.diffs

(if you retrieved the diffs as jdk1.1.8.diffs.bz2 do

   bzip2 -dc jdk1.1.8v2.diffs.gz | patch -NEp1
)

The patching process should flash by your eyes with a lot of "hunk succeeded"
messages.  The patch should not fail.  If it does, stop.  You're life is 
cursed, you will be unsuccessful in business, take up basket-weaving.

7) Do the build!
----------------

cd into "build/linux" and type "make build_release ; ./build_release".
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 166 Mhz @ JavaSoft, it would take
about an hour or a little more.  On my new 300 Mhz @ home, it takes
about (subjectively speaking) 30 minutes.  There will be times when it
seems to be doing nothing, especially when compiling a lot of Java
files.  Go out for a bagel while it compiles the byte to char
converters ... this used to take 4 hours alone on my 20M 66 Mhz DX/2
and is the longest, most boring part of the build.

It will build both the debug and the optimized versions of the runtime
system; to build just one or the other say "make debug" or "make
optimized".

The resulting binaries live in "build/bin".  You can invoke them
directly from there for instant "yes I've built it and it works"
gratification.  Yippee!!!

To do a real, full build of the world like I do in preparation for a
release, do "make DESTDIR=<somedir> appletviewer jre_only".  This
builds the entire system (appletviewer is the target causes everything
to be built) and the JRE system (which shows up in directories
"build/jre", "build/rt", and "build/i18n".  The "DESTDIR" variable
says where to put the resulting JDK; I often type
"DESTDIR=`pwd`/../../jdk1.1.8 when building in the build/genunix
directory, as this puts the results (but not JRE) into a directory
called "jdk1.1.5" that's a sibling of the top level "build" and "src"
directories.

To set the name of the release, use "RELEASE=mySpecialRelease" as a
parameter in your "make" command line (please pick a better release
name than I have here).

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

That's it!  



