Select Git revision
MAINTENANCE
MAINTENANCE 10.61 KiB
MAINTENANCE DOCUMENTATION FOR ALBERTA PACKAGES
Daniel Koester, April 2004
koester@math.uni-augsburg.de
Claus-Justus Heine, December 2003
claus@mathematik.uni-freiburg.de
I) Introduction and Maintenance
===============================
The alberta-x.x packages are now distributed using GNU autoconf 2.5*,
automake 1.7*, and libtool 1.5*. Since some unusual compilation was
necessary, a few hints seemed like a good idea. Here is the general
structure of the alberta-1.3 packages:
__________ ALBERTA/ __________ src/ _______|--- 1d/
/ \ |--- 2d/
/ -- doc/ |--- 3d/
/ |--- Common/
/_____________ DEMO/ __ src/ _______|--- 1d/ |--- ALBERTA?_??/
alberta-1.3/ * |--- 2d/
\_____________ ALBERTA_UTIL/ |--- 3d/
\ |--- Common/
\___________ PLOT_ANSI/ __ src/
\
\_________ SOLVER/ __ src/
\
\_______ GRAPE/ __ mesh/ ____|--- 2d/
\ |--- 3d/
\ |--- Common/
\
\___ MESHTV/ ___|--- 1d/
\ |--- 2d/
\ |--- 3d/
\ |--- Common/
\
\_ 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 simpler structure than "real" "Makefile.in"s
produced by automake.
2) The "Makefile.alberta.in" in ALBERTA/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: alberta-x.x/lib/ and alberta-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 alberta-1.3:
1) ALBERTA
The main package.
2) 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 becopied elsewhere by the user after installation. The Makefiles include
"Makefile.alberta" which resides in $installdir/include together with the
C-header files. They are meant to faciliate the first steps with ALBERTA.
3) ALBERTA_UTIL
This package contains the old ALBERTA util.c file, now split into several
smaller source files. It is compiled to form a separate utility library
(message macros, ALBERTA memory allocation routines, etc.) and should linked
to any program using the ALBERTA package.
It can also be used as a standalone utility library.
4) PLOT_ANSI
PLOT_ANSI provides tools for displaying X11 graphics, if gltools is not used.
5) SOLVER
Linear and nonlinear solver routines for ALBERTA.
6) GRAPE
GRAPE interface for ALBERTA
7) MESHTV
MeshTV interface for ALBERTA via the Silo library
III) External packages
======================
The gltools package is not part of ALBERTA. If it is detected during
installation, the file ALBERTA/src/Common/gltools.c is included in the ALBERTA
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. There is a very fine Info manual available. You
can view it with "info cvs", or -- better -- use Emacs as Info-reader.
Another very good source of information is
http://www.cvshome.org/
with the online-manual and online-FAQ at
http://www.cvshome.org/docs/manual/
http://ccvs.cvshome.org/fom//cache/1.html
(the latter link seems to be a bit funky, maybe better use the CVS
home page as entry point.)
There are a couple of front-end for CVS, e.g. an Emacs mode and many
others.
Step 0a)
Make sure the stuff you are checking in 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 ."
Step 2)
cvs commit
NOTE: this commits _all_ changed files. It is probably better
to commit on a file-per-file basis:
cvs commit FILE1 .... FILEN
with a selected collection of file you really want to commit.
ALSO: it is required that all commits are properly documented. The
comments must be written in a way that other people can understand
them.
Another possibility (avoiding Step 1) from above) is the following:
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/ALBERTA_CVS/ commit FILE1 ... FILEN
This will take care of setting the correct permissions and group
id's in the ALBERTA CVS repository. It will fail if you are not a
member of the access group "alberta", but then you shouldn't attempt
to commit changes at all, ask one of the ALBERTA maintainers for
help.
V) How to create a distribution
===============================
Step 0)
Become familiar with CVS.
Step 1)
At the moment, the subpackages ALBERTA, BLAS, DEMO, ALBERTA_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
"albertadist" module. Checking it out will create the ALBERTA
package with the directory structure described right at the
beginning of this file.
cvs co albertadist
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 albertadist
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 ALBERTA_2_0 albertadist
Afterwards, check out _that_ version of ALBERTA
cvs co -r ALBERTA_2_0 albertadist
Step 2)
The next step is to adjust the desired libraries, especially the
ALBERTA libraries. Each ALBERTA library has its own directory of the
form "ALBERTA[DIM_OF_WORLD]_[DEBUG=0 or 1][EL_INDEX=0 or 1]" since
compilation is different for each library version. If
these settings are to be changed, make a new directory, and adapt the
files "Makefile.am.template" and "generate-alberta-automakefiles.sh" in
the top directory.
Step 3)
Make sure you have a recent version of GNU automake, autoconf and
libtool and run "autoreconf" in the "albertadist" directory. At the
moment ALBERTA needs autoconf-2.5*, automake-1.7* and libtool-1.5*.
The version numbers of GNU programs can be checked by running
foobar --version
where you have to replace foobar by the proper name of the program.
The m4/ subdirectory contains (beside other files) modified versions
of the following standard libtool respectively autoconf macro files:
libtool.m4 -- changed the "-c -o" test (around line 946)
fortran.m4 -- needed to be changed to enable compilation on MacOS X
(Darwin)
Keep this in mind when upgrading to new versions of libtool and
autoconf. In particular, when upgrading one should check whether
those two hacks are still needed.
Step 4)
Rebuild the Makefile.am's for the ALBERTA libraries, this is done by
running the shell-script
./generate-alberta-automakefiles.sh
Then run remake all Makefile.in's (and all other auto-generated files):
autoreconf
Step 5)
Reconfigure ALBERTA with the additional switch
"--enable-maintainer-mode":
./configure BLABLABLA --enable-maintainer-mode
Step 6)
Do "[g]make dist" at the top level. This creates alberta-1.3.tar.gz
in which all CVS-directories, ~-files, and other unnecessary
components are stripped. To be a bit more precise:
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.
If you have an already configure version of ALBERTA, then you can make
a distribution by running
make generate-alberta-dist
which runs the steps 4.)-5.).
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.