// README.txt
// Copyright (c) 2001 MBruce, all rights reserved
// $Id: $
This directory contains a slightly modified version of "jam".
I highly recommend that you familiarize yourself with what
the standard "jam" does before trying to use this one. I'm
not even sure how useful this will be to most others.
First, credit where credit is due.
Although I am currently the curator for this, I was in no way
the author of any of this. These changes and modifications,
which make for one heck of a nice build process and build
environment, were all done by:
Randy Brown
Arefin Huq
Joe Bamberg
I only had the fortunate position of being their manager.
I have since made a few minor modifications, such as support
for JAMSHELL being "ksh" on UNIX and Linux, and better dependancy
analysis for Java that works around a few bugs in javac's
automatic dependancy checker.
Here are the basic changes added to this version of Jam:
o A few fixes to jam so that when a line that is going to be passed out to
the shell is more than 1024 characters, it dumps it to a ".bat" or a ".ksh"
file (depending on the platform). This gets around the maximum length of a
"ksh -c ......" command on most platforms.
o Most rules (99%) are loaded at runtime, instead of being compiled into
the program. This is so that on a branched project bases, we can modify the
rule set. (Otherwise, we have to have multiple versions of the 'jam.exe' or
'jam' on UNIX at the same time, each corresponding to a different jambase,
OR we have to have users remember which jambase to load. This loads a
jambase out of the TOP directory. Not all users might want this - it
complicates Jam but works better for us on a per project basis)
o C/C++ source files are built into either a subdirectory called "release"
for release objects or into "debug" for debug objects.
o Libraries are gristed to have the following features:
o a version number on all .a, .so, or .dll files
o "s" appended to the name for release builds on Micro$oft's compiler
o "g" appended to all debug .a, .so, or .dll files
o The same rules above apply to executables
o Links are done to the proper libraries on each of these
o Crunked up support for java. You can build java jar files, and there is
a special rule to build persistable java class files for object store. The
java building requires "ksh" to be installed on the machine and requires
that "JAMSHELL" be set to this ksh. The java support works as follows:
o Creates a java package file for each java directory in the project that
includes all of the subdirectories
o Creates a java root package that includes all the packages
o Calls the java compiler on the root package and lets the javac program
deal with the sub packages
There are several other crunks in the java packaging itself so that javac
will properly find the right directories.
There are quite a few rules that were built in to support
our build as well. I have tried to comment most of them out,
but there are still quite a few around. I will try to detail
as many as possible, time permitting.
So, on to some instructions on how to build and use this
version of Jam.
---------------------------------------------------------------
1. Building and Installing
---------------------------------------------------------------
I have provided binaries for this version of jam in the binaries
directory, however, it is hightly recommended that you build
your own. Here is how to do that:
1. Download the source for the standard Perforce version
of jam from the perforce public depot, or from
the jam web site
http://www.perforce.com/jam/jam.html
2. Build the standard version of jam by typing:
"make"
3. There is a subdirectory under here called "customJam"
That version of jam can only be built with a previous
version of Jam. To build the custom jam, go to the
customJam directory and run "jam". (this will be the
jam that you build in step 2 above)
Installing
The above build will make a version of jam called "bhbjam"
for Brown Huq and Bamberg jam. (See above for credits).
Place the "bhbjam" somewhere in your path. You should use
this version of jam to build everything else
----------------------------------------------------------------
2. Building the sample project with "bhbjam"
----------------------------------------------------------------
The sample project includes some C++ and some Java so that you
can watch bhbjam go to work on both. There are a few environment
variables you have to set to get "bhbjam" to work.
To set these on UNIX type:
export JAMSHELL=/bin/ksh
export TEMP=/home/mbruce/tmp # or some working tmp dir that is NOT shared
export CF=debug # you can set CF to debug or release
On Windoze NT type:
set JAMSHELL=c:\unix\sh
set TEMP=c:\temp
set CF=debug
You should note that on both UNIX and NT you MUST have a version of
ksh installed for this jam to work. Sorry. The java stuff is
kinda crunked in, so that is how it goes.
Go the the sampleProject directory and type
bhbjam
It will build everything for you. That is all there is to it.
------------------------------------------------------------------
3. Explanation of the custom rules built in
------------------------------------------------------------------
TODO: write these.