/*******************************************************************
 *                                                                 *
 *                         CHASM                                   *
 *                      Version 1.4.0                              *
 *                                                                 *
 *  README - a brief description and pointers to more information  *
 *                                                                 *
 *******************************************************************


                          DESCRIPTION
                          -----------

Chasm is a tool to improve C++ and Fortran 90 interoperability.  Chasm
parses Fortran 90 source code and automatically generates C++ bridging
code that can be used in C++ programs to make calls to Fortran
routines.  It also automatically generates C structs that provide
a bridge to Fortran derived types.  Chasm supplies a C++ array
descriptor class which provides an interface between C and F90
arrays.  This allows arrays to be created in one language and then
passed to and used by the other language.

Chasm works by parsing C++ and Fortran source files and generating an
XML file.  The XML file describes C++ classes, Fortran modules,
user-defined types, functions, and function parameters.  XSLT
stylesheets are used to transform the XML file into bridging code
that is used to call C++ and Fortran routines.

Chasm (version 1.1.0 and later) contains the Fortran, array descriptor
library.  This is a low-level C library used to manipulate Fortran array
descriptors (dope vectors).  It is the only way one can pass F90
assumed-shape arrays and array sections between C and Fortran.  This
library is primarily aimed at interoperability tool developers, rather
than end users.

The array descriptor library is completely tested and is considered
production-level quality.  Currently, other Chasm tools for generating code
for language interoperability are under development and are not tested, nor
are they complete.  The most mature are the tools for generating code for
calling Fortran from C++.  See the example/particle directory for an example
of how to use these tools.

Other examples of code generation can be found in the chasm/contrib
directory.  The chasm/contrib/NumPy directory demonstrates how to
use F90 arrays with the Python Numeric library.  The chasm/contrib/VTK
library generates Fortran wrappers to the C++ VTK library.  The code in
the contrib directory is for educational/intertainment purposes and
is not supported.

Of particular interest to some may be the tool to generate xml files,
describing interface-level information, from Fortran and C++ sources.  This
tool may be found in chasm/src/xmlgen.

                            RESOURCES
                            ---------

Installation instructions:

  - See the INSTALL file in the top Chasm directory (./INSTALL).

Documentation:

  - Still a little sparse, but see the doc directory for what currently
    available.  In particular, see ./doc/ArrayDesc-API.pdf for the
    documentation of the array descriptor library.

Help:

  - Please send e-mail to chasm-support@lanl.gov.

CVS Repository:

  - The public is free to check out the most recent copy of the Chasm CVS
    repository and experiment with the tools.  Any patches or changes that
    you wish to have added should be sent to chasm-support@lanl.gov. 
    Information regarding CVS checkout can be found off of the sourceforge
    web page:

       http://sf.net/projects/chasm-interop/


                           DIRECTORIES
                           -----------

./bin/
  - Scripts to call the XSLT stylesheets (needs work).

./contrib/
  - User contributed stylesheets.  Chasm is open source, please contribute
    stylesheets that you have developed and find useful.

./doc/
  - Documentation for the project.

./example/
  - Example files that can be used to generate bridging code.
    Examples in ./example/cca-tutorial illustrate the use of Chasm to 
    assist in generating CCA/Babel components from legacy F90, C, and
    C++ source.  

./include/
  - Include files for compiling Chasm-generated code.  In particular,
    include files for Fortran array descriptors.

./src/
  - C++ and C source files for the project.

./test/
  - Test files for the project.  Tests for the array descriptor library
    are in ./test/descriptors.

./xml/xst/
  - Contains XSLT stylesheets to generate bridging code.

