MAINTENANCE DOCUMENTATION FOR ALBERT PACKAGES
Daniel Koester, December 2002
dani@mathematik.uni-freiburg.de

I) Introduction and Maintenance
===============================

The albert-x.x packages are now distributed using GNU autoconf 2.53, automake 1.6, and libtool 1.4.2. Since some unusual compilation was necessary, a few hints seemed like a good idea. Here is the general structure of the albert-1.1 packages:

                 _________ ALBERT/ __________ src/ _______|--- 1d/
                /                         \               |--- 2d/ 
               /__________ BLAS/           -- doc/        |--- 3d/
              /                                           |--- Common/
             /____________ DEMO/ __ src/ _______|--- 1d/  |--- ALBERT??_??/
albert-x.x/ *                                   |--- 2d/  
             \____________ ALBERT_UTIL/         |--- 3d/
              \                                 |--- Common/
               \__________ PLOT_ANSI/ __ src/
                \
                 \________ SOLVER/ __ src/
                  \
                   \______ [gltools-2-3/] optional
                    \
                     \____ configure.ac and other distribution
                           files

We keep track of the "Makefile.am"s, which are processed by automake to create "Makefile.in"s. Two exceptions:
1) The "Makefile.in"s in DEMO/src/*d are independently maintained. They have a simple structure compared to "real" "Makefile.in"s produced by automake.
2) The "Makefile.albert.in" in ALBERT/src/Common/, see below.

The file "configure.ac" is processed by autoconf to create "configure". The script "configure" then processes "Makefile.in"s to create proper Makefiles. The created Makefiles can then be used by us to test compilation and the demo programs. All Makefiles can be called independently from any subdirectory. The "install"-target is used to install a package (defaults for maintenance: albert-x.x/lib/ and albert-x.x/include/ as installation paths for libraries and headers, no shared libraries). There are also several variations of "clean" targets.


II) Package contents
====================

The following subpackages are included in albert-x.x:
1) ALBERT
The main package.

2) BLAS
Basic Linear Algebra Subroutines, these are compiled if the system on which ALBERT will run does not supply them.

3) DEMO
A few demonstration programs. This package is not touched by automake and includes several small Makefile.in's in which configure substitutes values like installation paths for libraries and headers. This directory can be copied elsewhere by the user after installation. The Makefiles include "Makefile.albert" which resides in $installdir/include together with the C-header files. They are meant to faciliate the first steps with ALBERT.

4) ALBERT_UTIL
This package contains the old ALBERT util.c file, now split into several smaller source files. It is compiled to form a separate utility library (message macros, ALBERT memory allocation routines, etc.) and should linked to any program using the ALBERT package.
It can also be used as a standalone utility library.

5) PLOT_ANSI
PLOT_ANSI provides tools for displaying X11 graphics, if gltools is not used.

6) SOLVER
Linear and nonlinear solver routines for ALBERT.


III) External packages
======================

The gltools package is not part of ALBERT. If it is detected during installation, the file ALBERT/src/Common/gltools.c is included in the ALBERT libraries. The user can specify the path of an already installed gltools-package as a configure option, see INSTALL.

IV) Checking into CVS directory tree
====================================

Step 1)
Do [g]make clean cvs-clean. This deletes all files which are not part of the CVS directory tree, but are in the CVS-maintained directories. Also does "chgrp -R albert *"

Step 2)
  cvs commit


V) How to create a distribution
===============================

Step 1)
At the moment, the subpackages ALBERT, BLAS, DEMO, ALBERT_UTIL, PLOT_ANSI, and SOLVER are maintained using the version control system CVS. To prepare a distribution, one must first check out the distribution version of these packages. The CVS-module "admin" contains the main administration files like "configure.ac" and the main "Makefile.am" from the root directory. Using 

  cvs co ALBERT BLAS DEMO ALBERT_UTIL PLOT_ANSI SOLVER admin

also checks out CVS administration directories in each module. This is ok, since
Makefiles produced by configure have a fixed set of directories to be included in a distribution. Another possibility is

  cvs export ALBERT BLAS ...

which strips the CVS directories.

Step 2)
The next step is to adjust the desired libraries, especially the ALBERT libraries. Each ALBERT library has its own directory of the form "ALBERT[DIM][DIM_OF_WORLD]_[DEBUG=0 or 1][EL_INDEX=nothing or 1]" since compilation is different for each library version. If these settings are to be changed, make a new directory (as in ALBERT13_0[1]) for example, create a copy of the Makefile.am from another directory and adjust the obvious settings like "DIM", "DIM_OF_WORLD", etc. The Makefile.am in these directories uses VPATH to find sources in src/?d and src/Common. 

Step 3)
Do "[g]make dist" at the top level.
This creates albert-x.x.tar.gz in which all CVS-directories, ~-files, and other unnecessary components are stripped. To be a bit preciser:

a) All sources and headers are included, of course.

b) All "Makefile.am"s and "Makefile.in"s are included. Ideally, the user simply
enters "configure" followed by "[g]make", "[g]make install" to install everything.

c) "configure" AND "configure.ac" are included, so that possible installation problems can (hopefully) be corrected after feedback with us.


V) Possible problems and tested platforms
================================

Some things are already explained in "configure.ac". If not explicitly stated otherwise below, "configure" will run without extra command line options.
Choosing not to use libtool would require many changes, the first would be to change all "LTLIBRARIES" to "LIBRARIES" in all "Makefile.am"s.

1) mips-sgi-irix6.5:
  a) The -lgl and -lGL libraries are required.
  b) The GNU Fortran compiler g77 distributed by SGI produced n32-style code, which was not default for
     the gcc. Recommended solutions:
    i) Adding -n32 option to "CFLAGS" and "LDFLAGS", if $CC == gcc and %F77 = g77.
    ii) Using the system compilers cc and f77.

2) i686-suse-linux:
  a) We used MesaGL and a BLAS lib included in our distribution. If MesaGL is not found, "configure" will also try "GL". The BLAS lib needed -lg2c to process FORTRAN code properly.

3) sparc-sun-SunOS:
  a) For the xdr-Routines, the library -lnsl seemed necessary.
  b) In our case, "configure" did not automatically recognize the canonical system triplet. Calling "configure --build=sparc" worked.