diff --git a/MAINTENANCE b/MAINTENANCE
index 7a7f21b4bd3cf2846b11982153790fd63ca43ccd..eb729312e63d8fd5fa887dad5a907a25b1d4ac93 100644
--- a/MAINTENANCE
+++ b/MAINTENANCE
@@ -7,28 +7,43 @@ 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.2 packages:
- _________ ALBERT/ __________ src/ _______|--- 1d/
- / \ |--- 2d/
- /__________ BLAS/ -- doc/ |--- 3d/
- / |--- Common/
- /____________ DEMO/ __ src/ _______|--- 1d/ |--- ALBERT??_??/
-albert-1.2/ * |--- 2d/
- \____________ ALBERT_UTIL/ |--- 3d/
- \ |--- Common/
- \__________ PLOT_ANSI/ __ src/
+ __________ ALBERT/ __________ src/ _______|--- 1d/
+ / \ |--- 2d/
+ /___________ BLAS/ -- doc/ |--- 3d/
+ / |--- Common/
+ /_____________ DEMO/ __ src/ _______|--- 1d/ |--- ALBERT??_?/
+albert-1.2/ * |--- 2d/
+ \_____________ ALBERT_UTIL/ |--- 3d/
+ \ |--- Common/
+ \___________ PLOT_ANSI/ __ src/
\
- \________ SOLVER/ __ src/
+ \_________ SOLVER/ __ src/
\
- \______ [gltools-2-3/] optional
- \
- \____ configure.ac and other distribution
- files
+ \_______ GRAPE/ __ mesh/ ____|--- 2d/
+ \ |--- 3d/
+ \ |--- Common/
+ \
+ \___ [gltools-2-4/] 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.
-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.
+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
@@ -39,13 +54,22 @@ The following subpackages are included in albert-1.2:
The main package.
2) BLAS
-Basic Linear Algebra Subroutines, these are compiled if the system on which ALBERT will run does not supply them.
+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.
+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.
+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
@@ -54,68 +78,169 @@ PLOT_ANSI provides tools for displaying X11 graphics, if gltools is not used.
6) SOLVER
Linear and nonlinear solver routines for ALBERT.
+7) GRAPE
+GRAPE interface 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.
+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 0)
+ Become familiar with CVS.
+
+Step 0a)
+ Make sure the stuff you are checkingin at least builds without errors.
+
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 *"
+ 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
+ BIG FAT WARNING: this commits _all_ changed files. It is probably bette
+ to commit on a file-per-file basis.
+
+ ALSO: it is required that all commits are properly documented. The comments
+ must be written in a way that other people can understand them.
+
+ There are a couple of front-end for CVS, e.g. an Emacs mode, a TCL interface,
+ and even when using CVS from the command-line, it is not necessary to commit
+ everything at once. So maybe better do:
+
+Step 2-preferred)
+ cvs commit FILE1 .... FILEN
+ with a selected collection of file you really want to commit.
+
+Step (1 and 2-preferred)-alternative)
+ Check out the "cvs.sh" script:
+
+ cvs co admin-utils/cvs.sh
+
+ Then do the follwing
+
+ mkdir $HOME/bin
+ mv admin-utils/cvs.sh $HOME/bin/cvs
+
+ Then edit your rc-scripts and modify your PATH variable:
+
+ bash-flavour: add the following to the end of $HOME/.bashrc
+
+ export PATH=$HOME/bin:$PATH
+ csh or tcsh flavour: add the following to the end of $HOME/.cshrc
+
+ setenv PATH ${HOME}/bin:${PATH}
+
+ For the settings to take affect you have to re-source the rc-files:
+
+ bash:
+ . ~/.bashrc
+
+ tcsh:
+ source ~/.cshrc
+
+ Then run cvs like follows:
+
+ cvs -d :ext:USER@COMPUTER.mathematik.uni-freiburg.de:/net/sauron/graid/ALBERT_CVS/ commit FILE1 ... FILEN
+
+ This will take care of setting the correct permissions and group id's in
+ the ALBERT CVS repository. It will fail if you are not a member of the
+ access group "albert", but then you shouldn't attempt to commit changes
+ at all, ask one of the ALBERT maintainers for help.
V) How to create a distribution
===============================
+Step 0)
+Become familiar with CVS.
+
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
+At the moment, the subpackages ALBERT, BLAS, DEMO, ALBERT_UTIL, PLOT_ANSI,
+GRAPE 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. To this aim there exists an "albertdist" module. Checking it
+out will create the ALBERT package with the directory structure describe
+right at the beginning of this file.
- cvs co ALBERT BLAS DEMO ALBERT_UTIL PLOT_ANSI SOLVER admin
+ cvs co albertdist
-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
+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 ...
+ cvs export albertdist
which strips the CVS directories.
+Actually, when making a _real_ distribution (i.e. you are not only playing
+with "make dist", you should set a symbolic tag with cvs _first_, e.g.
+
+ cvs rtag ALBERT_2_0 abertdist
+
+Afterwards, check out _that_ version of ALBERT
+
+ cvs co -r ALBERT_2_0 albertdist
+
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.
+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 3a)
+Make sure you have a recent version of GNU automake, autoconf and libtool
+and run "autoreconf" in the "albertdist" directory.
Step 3)
Do "[g]make dist" at the top level.
-This creates albert-1.2.tar.gz in which all CVS-directories, ~-files, and other unnecessary components are stripped. To be a bit preciser:
+This creates albert-1.2.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.
+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.
+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.
+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:
+ 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.
+ 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.
\ No newline at end of file
+ b) In our case, "configure" did not automatically recognize the canonical
+ system triplet. Calling "configure --build=sparc" worked.
diff --git a/README b/README
index ce6dd18a3a2f60fa9596f27a577cade869cd65c2..05778cd1faf22eb504b4a82aef0bca458ea0b778 100644
--- a/README
+++ b/README
@@ -8,22 +8,26 @@ I) Introduction
This is ALBERT Version 1.2. For the installation process refer to INSTALL.
Contained in the package are the following subpackages:
- _________ ALBERT/ __________ src/ _______|--- 1d/
- / \ |--- 2d/
- /__________ BLAS/ -- doc/ |--- 3d/
- / |--- Common/
- /____________ DEMO/ __ src/ _______|--- 1d/ |--- ALBERT??_?/
-albert-1.2/ * |--- 2d/
- \____________ ALBERT_UTIL/ |--- 3d/
- \ |--- Common/
- \__________ PLOT_ANSI/ __ src/
+ __________ ALBERT/ __________ src/ _______|--- 1d/
+ / \ |--- 2d/
+ /___________ BLAS/ -- doc/ |--- 3d/
+ / |--- Common/
+ /_____________ DEMO/ __ src/ _______|--- 1d/ |--- ALBERT??_?/
+albert-1.2/ * |--- 2d/
+ \_____________ ALBERT_UTIL/ |--- 3d/
+ \ |--- Common/
+ \___________ PLOT_ANSI/ __ src/
\
- \________ SOLVER/ __ src/
+ \_________ SOLVER/ __ src/
\
- \______ [gltools-2-4/] optional
- \
- \____ configure.ac and other distribution
- files
+ \_______ GRAPE/ __ mesh/ ____|--- 2d/
+ \ |--- 3d/
+ \ |--- Common/
+ \
+ \___ [gltools-2-4/] optional
+ \
+ \_ configure.ac and other distribution
+ files
1) ALBERT
The main package.
@@ -44,6 +48,14 @@ PLOT_ANSI provides tools for displaying X11 graphics, if gltools is not used.
6) SOLVER
Linear and nonlinear solver routines for ALBERT.
+7) GRAPE
+GRAPE interface for ALBERT. Only for non-parametric FE of dimension 2 and 3.
+"make" will create "albert_grapeXX" and albert_moviXX" where XX is in {22, 33}.
+"make install" will install those programs below PREFIX/bin.
+
+The GRAPE interface is only installed when the GRAPE library and header file
+are available on your system (determined at configure time, use
+"configure --help" for apropriate command line switches for "configure").
II) External packages
=====================
@@ -54,24 +66,45 @@ The gltools package is not part of ALBERT. If it is detected during installation
III) Configure options
======================
-The configure file accepts an option called
+"configure --help" will give you a summary of available options. The file
+"INSTALL" contains generic configuration instructions and a description of
+generic command line options for configure.
- --with-gltools=PATH
+The remaining (i.e. ALBERT specific) options are explained here:
-where PATH is the path of a gltools-2-4 directory possible installed on the system. The default value where gltools-2-4 is searched is the build directory.
-The default installation path is also the build directory. This can be changed via
+ --with-gltools=PATH
+ PATH is the path of a gltools-2-4 directory possible installed
+ on the system. The default value where gltools-2-4 is searched
+ is the build directory. The default installation path is also
+ the build directory. This can be changed via
--prefix=PREFIX install architecture-independent files in PREFIX.
-
-Default library mode is to install static and shared libraries. Change this via
+ NOTE: this is different from the default GNU installation prefix,
+ which would be "/usr/local/".
--enable-shared=?? and/or --enable-static=??
-
-where ?? is "yes" or "no". Finally, the option
+ Default library mode is to install static and shared libraries.
+ This can be changed using these switches,
+ where ?? is "yes" or "no".
--enable-el_index
-
-builds versions of the ALBERT libraries with C Preprocessor macro "EL_INDEX" set to 1. See the ALBERT documentation for details.
+ builds versions of the ALBERT libraries with C Preprocessor
+ macro "EL_INDEX" set to 1. See the ALBERT documentation for
+ details.
+
+ --without-GRAPE
+ do not even attempt to detect GRAPE. As a result, the GRAPE
+ interface will not be compiled.
+
+ --with-GRAPE-lib=DIR
+ Location of "libgr.a" or "libgr.so" on your system. If
+ "libgr.so" is installed at "/foo/bar/lib/libgr.so", then DIR
+ should be set to "/foo/bar/lib/".
+
+ --with-GRAPE-headers=DIR
+ Location of the GRAPE header file "grape.h". If "grape.h" is
+ installed at "/foo/bar/include/grape.h", then DIR should be
+ set to "/foo/bar/include/".
We recommend setting the environment variables "CFLAGS" and "FFLAGS" to "", so that "configure" does NOT automatically substitute a "-g" debugging option while compiling, as well as using the highest possible optimization flag "-O???" during a build of (non-debug) libraries.