----------------
NIST Sparse BLAS
----------------

---------------------------------------------------
Information on the source code generation mechanism:
---------------------------------------------------

   The distribution's SRC_GEN directory contains generic source files:

bcomm.c         bsrmm.c         cscmm.c         csrmts.c
bscmm.c         bsrmts.c        cscmts.c        vbrmm.c
bscmts.c        coomm.c         csrmm.c         vbrmts.c

along with generator scripts for creating the NIST Sparse BLAS kernel 
routines from these generic source files.

   These source files are used as "master files", and are written in such
a way that special case routines can be generated by relatively simple
shell scripts which use "sed" and "awk" for text replacement.
The approach saves considerable programming effort by generating most
source files automatically, and reduces errors by ensuring that
any changes are propagated throughout all of the related source code.

   The master files provide working source code for the most general
version of the kernel routine.  This is where real programming effort
should be expended to optimized the library.  The code is commented
with tags which can be used to selectively delete code for special
case routines.   The "rules" for creating each special case file 
are defined in the SRC_GEN/kernels subdirectory.  The kernels subdirectory
contains the files

CAB		CADBbC		CDADBC		CaADB		CaDABbC
CABC		CDAB		CDADBbC		CaADBC		CaDADB
CABbC		CDABC		CaAB		CaADBbC		CaDADBC
CADB		CDABbC		CaABC		CaDAB		CaDADBbC
CADBC		CDADB		CaABbC		CaDABC

one representing each of the specializations from the generic master
code, along with kernel files for the master codes.  Each of these
kernel files contains pointers to appropriate "Definition" files,
in the directory SRC_GEN/Defs, which are used to build up the 
sed script for the text replacement to generate the kernel routines.

   For typical use, these kernel and definition files would never have 
to be touched.  Many modifications (say for optimization) can be made 
to the master source files without requiring any change whatsoever 
to the file generation mechanism.  The only source code changes which
would affect code generation would be those which alter the 
relationship between the comment tags and the related source.
A more detailed explanation of the mechanism, and requirements
for modifications, will be forthcoming in the 1.0 release.

   After making any necessary changes to these "master" source files, 
the library source files may be generated via the "create" script
(automated in the "make" process in this directory with "make install" 
or "make re-install").

                          ** IMPORTANT NOTE **

   Any changes to source for any routines below the Toolkit interface 
layer ** MUST ** be made in the ../SRC_GEN directory to be retained and 
propagated to all appropriate kernel routines. 

   Changes to the Toolkit interface routines, however, should be made 
directly in the directory ../src_tk[c|f].)

                          ** IMPORTANT NOTE **