README.linux.src for JDK 1.1.6, Version 1 Steve Byrne java-linux@java.blackdown.org 5/18/98 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.5 binaries and installing them, although you can build with the JDK 1.1.3 binaries (since you're reading this, you've probably been smart enough to follow my advice and get the 1.1.5 binaries -- good choice!). The 1.1.3 binaries will work, but if you haven't provided enough memory for building, you'll get a crypting error about assertion failure in monitor_md.c and the build will halt (1.1.5 properly tells you that "hey dude, you're out of memory"). (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 (I use 2.7.2.1). 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. 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.83 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.5. 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 "genunix". cd up and over into the "src" directory. Rename that "solaris" directory to also be called "genunix". 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 -p1 < jdk1.1.5.diffs (if you retrieved the diffs as jdk1.1.5.diffs.gz do zcat jdk1.1.5.diffs.gz | patch -p1 ) 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/genunix" and type "make". 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= 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.5 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!