#**********************************************************************
#* Copyright (c) 2003, 2004 Hyades project.
#* All rights reserved.   This program and the accompanying materials
#* are made available under the terms of the Common Public License v1.0
#* which accompanies this distribution, and is available at
#* http://www.eclipse.org/legal/cpl-v10.html
#* 
#* Contributors: 
#* IBM - Initial API and implementation
#**********************************************************************

Big-picture "how this project is structured notes
=================================================

This top-level "BCI" directory contains source code for the
Probekit byte-code instrumentation engine. Here is the
subdirectory structure and what each subdir has in it:

BCIEng
	Contains the top-level Microsoft Visual Studio 6 workspace file,
	and the abstract base classes for CModule, CMethod, and
	instruction sets. Also has BCIEngInterface.h, which defines
	the C-callable interface to the instrumentation engine.

BCIEngJ
	Contains the Java-specific implementations of the abstract
	base classes: CModuleJ, CMethodJ, CInsSetJ, etc.

BCIEngProbe
	Contains the Probekit specific logic that uses the generic BCI 
	facilities to implement the probe system.

BCIEngProbe/ProbeInstrumenter
	Contains source for the command-line executable application
	that can apply probes to class flies on disk.

Common
	Contains headers that contain most of the platform-dependent
	ifdefs, typedefs, and macros for this project. Also contains
	some helper classes and utilities.

JClass
	Contains the Java class file reading and writing logic.

JDump
	Contains a utility program for dumping Java class files. This
	utility program does not build when you "make" the rest of the
	project, and it does not ship with Hyades.

GENERAL BUILDING NOTES
======================

At the BCI directory level you can run "make" using the platform-appropriate
makefile and the project will build. The top-level makefile is almost empty:
all it does is cd down to the BCI/BCIEng/BCIEngProbe/ProbeInstrumenter directory
and make that.

The ProbeInstrumenter directory's makefile first cd's to the directory it depends
on (its parent) and runs make there; then it makes its own target. All the 
makefiles in this project work that way: they first cd to the directories 
containing things they depend on and run "make" there, then they make their 
own targets.

UNIX NOTES
==========

Build
-----
In the best of all worlds, to build from this directory ("BCI"),
just do this:

   % make -f makefile.unix

If you use the "package" target, the build will produce a
probekit.zip in this directory, which you can easily drop into
your plugin for deployment.

In more detail:

Each source directory contains a Makefile.unix for building that
component. Platform-specific build customizations should be made in:

   Common/Makefile.include

This makefile uses uname to determine which platform you're on and
applies suitable customizations. Among other things, it puts both
hardware and OS specific defines on the compiler command line so the
sources can be suitably tailored. See Makefile.include for details;
if you're adding a new platform or want to use a different compiler,
this is the place to start.

To produce a debug build, use:

   % make -f makefile.unix debug=yes

Makefiles and sources have been tested successfully using:

- GNU make
- Solaris 2.7 and above, Forte 6 Update 2 (5.3) or later
- Red Hat Linux 7.3 or later, gcc 2.96 or later

It may work with older Forte compilers; I didn't try. It probably works 
with older OS versions, but has not been tested there. 

To override the compiler names, define CC and CXX on the make command line.
For example, in our environment, Forte 6 Update 2 is "CC5.3" so I use:

   % gmake CC=cc5.3 CXX=CC5.3 

However, if you're *really* changing compilers (Forte to GNU on Solaris, for 
example) rather than just changing the name, you'll need to make other
changes. See Makefile.include.

See "Unfinished Business", below, for caveats about the sea-worthiness of 
the current build.

If you use the default target (all), the required pieces are left in
./Release or ./Debug, depending on whether or not debug=yes was on the
make command line.

Test
----
To test what you built, you will need the probeinstrumenter executable,
ProbeInstrumenter.jar, a probescript generated by the probe compiler,
and the class file you to run as a test. See the Hyades help for
more information. 

Porting
-------
If targetting a new Unix variety, start with Common/Makefile.include.
Common/CommonDef.h attempts to encapsulate most of the known platform
differences, so it should be your second stop.

In addition, wherever possible (or I thought of it ahead of time!), I've
tried to set the source files up so that you will get a compilation error
if there is a place likely to require platform-specific configuration by
doing things like this:

   #ifdef _WINDOWS_
   blah blah
   #elif defined(SOLARIS)
   blah
   #elif ...
   ...
   #else
   #   error "Platform specific configuration required."
   #endif

No doubt this will be annoying, but it is infinitely preferable to 
stubbing your toes on these problems at runtime.

Unfinished Business
-------------------
 - Currently the build produces a clutch of archive libraries; this is
   definitely not correct. It should at least produce a single archive
   library. More accurately, it should produce a shared library with
   external C++ runtime dependencies resolved as needed, so that we don't
   distribute an exe with dependencies that might not be resolvable on 
   the end users's host. 

   The makefiles already build PIC by default and there are shared lib 
   targets in each of the sub-makes, but nothing is in place to build one 
   big ball-of-mud shared lib. Nor have I given any thought to which
   external dependencies are OK (if any) and which are not.

 - The build should write all output to a platform specific directory so
   you can build multiple platforms in one dir tree. Currently, it writes
   output next to the sources files, so only one platform at a time can
   build into the dir hierarchy.

 - There's a cross-platform, porting land mine lurking in 
   BCIEng/BCIEngProbe/BCIEngProbeInterface.cpp. It parses out the
   Probekit.txt file and uses newlines as a command separator...but
   newlines vary between windows and unix, between ASCII and EBCDIC.
   I've hacked it up to work between Windows and the test Unix flavors
   which use ASCII. See breat_into_lines() in this file for details.

   It is felt that the use of this text file is a temporary artifact, so 
   maybe we'll never really have to confront the problem, but then again...

WINDOWS NOTES
=============

Build
-----
Tested with Visual Studio 6, using the GUI. Use ProbeInstrumenter as the
target project. Note that the executables are built into the parent
directory's Release and Debug directories.

There are also exported makefiles you can use to build with nmake. Use:

   nmake /f makefile.win_ia32
   
If you want a debug build, you'll need to set "CFG" on the nmake command
line. See the makefile for details.
