BUGS:

This file lists known bugs and non-bugs that
often trip people up.  Most of these bugs are
the result of incompatibilities among compilers 
and various Unix systems.

------------------------------------------------------------

CONTENTS:

0. configure --disable-shared causes CCA example not to compile
1. Mixing KAI C/C++ with non-KAI Fortran:
2. Creating C++ Archives
3. Catching Exceptions in Shared Libraries (g++)
4. Catching Exceptions in C++ bindings
5. Mixing GNU and Non-GNU Compilers
6. Configuration Exits with a Cross-Compilation Warning or Compiler Error
7. MacOSX file corruption after downloads
8. Archiver dumps core on Solaris in the libdecaf directory
9. JVM quits on libzip.so (1.1.3) incompatibility with libz.so
   from zlib used by libxml2.so.

------------------------------------------------------------

0. configure --disable-shared causes the CCA example not to compile.

The Makefiles for the CCA example aren't smart enough to build the CCA
example when shared libraries are disabled.

------------------------------------------------------------

1. Mixing KAI C/C++ with non-KAI Fortran:

Symptom:
KCC complains that fortran libraries are not found at link time.

Diagnosis:
Configure generates an '$(FLIBS)' Makefile macro that contains
the correct "-lf2c" and "-L/path/where/f2c/is" arguments.  However, 
the "-l*" argument may appear _before_ the "-L*" argument, which
seems to be a problem for KCC.  If the ordering of these two are
reversed, the problem is fixed.

Solution:
Not our bug. Either autoconf should build a better macro, 
or KCC should load all the "-L*" arguments before giving up.

Workaround:
We have created an autoconf macro called LLNL_SORT_FLIBS that re-sorts
the FLIBS library list such that all of the "-L*" arguments preceed all
of the "-l*" arguments.

------------------------------------------------------------

2. Creating C++ Archives

Problem:
For most---if not all---C++ compilers, shared libraries may only be
created using the C++ compiler itself, not the standard archiver or
linker.  If the C++ compiler is not used as the archiver, templates
are not instantiated and exceptions may not work properly.  Unfortunately,
GNU libtool does not currently support the creation of C++ shared
libraries in a portable manner.

Solution:
Not our bug.  Fix Unix.  Fix compilers.

Workaround: 
We have hand-edited our version of libtool to build shared libraries
correctly for g++ (which should be portable across platforms), CC on
Solaris, and KCC (which should also be portable across platforms).
Archiving C++ with libtool is known to be broken on SGI and Cygwin.

------------------------------------------------------------

3. Catching Exceptions in Shared Libraries (g++)

Problem:
Exception handling works in static linked libraries, 
but switching to shared libraries may cause the exceptions
to go directly to abort() without any chance of being 
caught.

Diagnosis:
You must use the C++ compiler to create the shared library.
Earlier versions of g++ did not support exceptions in shared
libraries.

Solution:
Not our bug.

Workaround:
See bug #2 above; hand-edit libtool to create the shared library correctly.

------------------------------------------------------------

4. Catching Exceptions in C++ bindings

Problem:
Foo_bar() declares (in SIDL) that it throws ParentException.
The implementation actually throws a ChildException which inherits
from ParentException.  In C++ the client cannot catch ChildException,
only ParentException.

Diagnosis:
In C++ you are catching the smart-pointer classes to the
exceptions.  These smart pointers do not mirror the inheritance
heirarchy, so you must catch _exactly_ the types that are
declared as thrown from the method.  Once caught, you
can always try downcasting to more refined types and 
act accordingly.

Example:
See regression/exceptions/runCxx/excepttest.cc  
Note that TooDeepException and TooBigException
both inherit from FibException, but that we cannot
catch these two types directly.  Instead we catch
the base class and downcast as needed.

------------------------------------------------------------

5. Mixing GNU and Non-GNU Compilers

Problem:
Incorrect flags are passed to the linker, C and C++ compilers, or to libtool.

Diagnosis:
The configuration script and libtool can get confused if you mix GNU
and non-GNU tools.  Specifically:

	- mixing the GNU linker ld with non-GNU compilers (either C or C++)

	- mixing GNU and non-GNU C and C++ compilers

There does not seem to be a problem mixing g77 and f77 with other GNU and
non-GNU compilers.

Solution:
Not our bug.  Don't mix different linkers, C compilers, and C++ compilers.

Workaround:
We have edited our configuration utility to ensure that GNU and non-GNU
tools are not mixed.  If they are mixed, the configuration aborts with an
error.  Make sure your PATH contains the appropriate tools or explicitly
specify the desired compilers and linkers using environment variables before
you run configure.

------------------------------------------------------------

6. Configuration Exits with a Cross-Compilation Warning or Compiler Error

Problem:
The Babel configuration script terminates, complaining that you are
running as a cross-compiler or that the compilers are not installed
properly.

Diagnosis:
The configuration script cannot run the g++ compiler because it cannot
dynamically load the standard g++ shared libraries.

Solution:
Add the g++ standard libraries to your LD_LIBRARY_PATH.

------------------------------------------------------------

7. MacOSX file corruption after downloads

Problem:
Some files with long paths may be corrupted after download on a Mac running
OSX.  In particular, we have received reports that the name of file:

	compiler/gov/llnl/babel/symbols/SymbolRedefinitionException.java

is truncated.

Diagnosis:
This is a bug in the StuffIt Expander tool.

Solution:
Do not let the download manager unpack the distribution.  Instead, use the
MacOSX comand-line tool tar to expand the filename.

------------------------------------------------------------

8. Archiver dumps core on Solaris in the libdecaf directory

Problem:
The ar archiver dumps core on Solaris when archiving the libdecaf files in
the example directory.

Diagnosis:
The archiver /usr/ccs/bin/ar does not understand long symbol names that are
often generated by C++ compilers on codes with templaes.  These long symbol
names cause the archiver to dump core.

Solution:
We suggest you try a different archiver.  Our GNU archiver in /usr/local/bin/ar
does the trick for us.

------------------------------------------------------------

9. JVM quits on libzip.so (1.1.3) incompatibility with libz.so
from zlib used by libxml2.so.

Problem:
Most if not all java runtimes load an old libzip.so which defines
the same functions as libz.so 1.2.3 used by libxml2 in some
Linux distributions.  Java crashes as a result.
Libxml2 supports babel dynamic class loading, and this bug does
not affect static-linked babel applications (which cannot include
java anyway).

Solution:
Packaging error on the part of Sun. A future version of babel
will make it possible to use dynamic loading without using libxml2.
Support for this feature in the 1.0 series of releases is not expected.

Workaround:
User's who must have use java with Babel on affected Linux
distributions will need to build their own libxml2 with
configure option --without-zlib.
