Guidelines for contributing/maintaining code in ScaLAPACK
=========================================================

Here are some of the tools and "tricks of the trade" that I use
to maintain ScaLAPACK.

1.  Since 1999, ScaLAPACK is maintained in cvs.  ~susan/CVS/SCALAPACK/.

2.  ScaLAPACK is ANSI standard Fortran 77 (no extensions like
    DO ... END DO, DO WHILE, dynamic memory allocation, etc)
    We do, however, allow subroutine names longer than 6
    characters.

    ScaLAPACK is backward compatible.  If you need to change
    the calling sequence to an existing routine, or its amount
    of workspace, then you MUST create a new routine.  You
    cannot make any change that would break a user's existing
    code calling ScaLAPACK.

3.  Ftnchek  (syntax checker for ANSI Fortran 77)

          http://www.dsm.fordham.edu/~ftnchek/

    The most useful options to ftnchek are:

      ftnchek -declare -noextern -portability -library *.f > ~/listing

    For example, if I want to check the s.p.complex and d.p.complex
    EIG codes (source and testers), I would type:

    alias ftnchek 'ftnchek -declare -noextern -portability -library'
    cd SCALAPACK/TESTING/EIG
    ftnchek pc*.f c*.f pz*.f z*.f ../../SRC/pc*.f ../../SRC/c*.f \
            ../../SRC/pz*.f ../../SRC/z*.f ~/eig.listing

    and then view the listing file for errors...

    Be aware that d.p.complex is not part of the ANSI standard, so
    it won't recognize a lot of the COMPLEX*16 stuff, and will thus
    give a lot of extraneous error messages.

4.  NAGWare Fortran 77 tools  (nag_decs, etc)

      http://www.nag.co.uk/nagware/NQ.asp

    These tools polish the new codes so that they conform to
    to the ScaLAPACK style.   I use the same for LAPACK.

5.  Portability testing (compiler flags for subscript 
    checking and uninitialized variables...)  

    SGI IRIX64

      f77 -g -DEBUG:subscript_check=ON -trapuv *.f

    ALPHA Tru64

      f77 -C=all *.f

    AIX

      xlf -C *.f

    Solaris

      f77 -C *.f 

    After getting ScaLAPACK to run solely on each of these
    machine types, you then must spawn heterogeneous jobs
    mixing Alphas and IRIX machines, and so on.  For hints
    of known heterogeneous failures, consult the errata.html.

    You can also try native MPI versus MPICH in testing.

    If the code passes these tests, then we say that it can
    be included in ScaLAPACK.

6.  Documentation.  Installation Guide and Users' Guide are
    maintained in LaTeX.  Must be able to generate ps, pdf,
    and html version (using latex2html).

.