Select Git revision
MAINTENANCE
MAINTENANCE 10.30 KiB
MAINTENANCE DOCUMENTATION FOR ALBERTA PACKAGES
Daniel Koester, April 2005
koester@math.uni-augsburg.de
Claus-Justus Heine, December 2003
claus@mathematik.uni-freiburg.de
I) Introduction and Maintenance
===============================
The alberta-2.0 package is currently distributed using GNU "autoconf 2.59",
"automake 1.9.1", and "libtool 1.5.8". Since some unusual compilation was
necessary, a few hints seemed like a good idea. Here is the general
structure of the alberta-2.0 packages:
__________ alberta/ __________ src/ _______|--- 1d/
/ \ |--- 2d/
/ -- doc/ |--- 3d/
/ |--- Common/
/_____________ demo/ __ src/ _______|--- 1d/ |--- alberta*/
alberta-2.0 / |--- 2d/
\ |--- 3d/
\ |--- Common/
\
\__________ alberta_util/ ___ src/
\
\
\_______ add_ons/ ---- 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 (default
for maintenance: $installdir=./ ). There are also several variations of
"clean" targets.
For the portable building of shared libraries we use "libtool". This involves
special compilation, e.g.
libtool --mode=compile gcc ...
and
libtool --mode=link gcc ...
By default we therefore install a configured version of "libtool",
"libtool.alberta", in the $install_dir/libexec directory. This behaviour can be
turned off.
II) Package contents
====================
The following subpackages are included in alberta-2.0:
1) alberta
The main package.
2) demo
A few demonstration programs meant to faciliate the first steps with ALBERTA.
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 is installed as a tarball in
$installdir/share/alberta, but can be copied by users to other locations.
The Makefiles in demo include "Makefile.alberta" which resides
in $installdir/share/alberta.
3) alberta_util
This package contains the old ALBERTA util.c file, now split into
several smaller source files. As of version 2.0, alberta_util also
contains the former "SOLVER" library.
It is compiled to form a separate utility library (message macros,
ALBERTA memory allocation routines, BLAS solver routines and wrappers) and
should linked to any program using the ALBERTA package. It can also be used as
a standalone utility library.
4) add_ons
add_ons contains extra tools built on top of ALBERTA. At the moment it contains
GRAPE and SILO/MESHTV data visualisation interfaces for ALBERTA.
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 Subversion directory tree
====================================
Step 0)
Become familiar with Subversion. A very good source of information is
http://svnbook.red-bean.com/
with the online-manual and online-FAQ at
http://subversion.tigris.org/faq.html
Step 0a)
Make sure the stuff you are checking in at least builds without
errors.
Step 1)
Do [g]make clean svn-clean. This deletes all files which are not
part of the Subversion directory tree, but are in the Subversion-maintained
directories.
Step 2)
svn update
This step will make sure that the changes made simulataneously by other
maintainers do not interfere with the new local changes.
svn commit
NOTE: this commits _all_ changed files. It is probably better
to commit on a file-per-file basis:
svn 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.
V) How to create a distribution
===============================
Step 0)
Become familiar with Subversion.
Step 1)
At the moment, the subpackages alberta, demo, alberta_util,
and add_ons are maintained using the version control
system Subversion. 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.
svn checkout svn+ssh://marbella.math.uni-augsburg.de/homes/andere/alberta/ALBERTA_SVN/trunk albertadist
also checks out 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
svn export svn+ssh://pizza.math.uni-augsburg.de/homes/andere/alberta/ALBERTA_SVN/trunk albertadist
which is faster and strips the .svn directories.
Actually, when making a _real_ distribution (i.e. you are not only
playing with "make dist", you should set a tag with svn
_first_. Afterwards, check out _that_ version of ALBERTA
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 "alberta2_[DIM_OF_WORLD]d[_debug]" 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)
Rebuild the Makefile.am's for the ALBERTA libraries, this is done by
running the shell-script
./generate-alberta-automakefiles.sh
Step 4)
Make sure you have a recent version of GNU "automake", "autoconf" and
"libtool" and run "autoreconf" in the "albertadist" directory. We
recommend running "autoreconf --install --force" to be certain that
everything will work as expected.
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.
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-?.?.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 configured version of ALBERTA, then you can make
a distribution by running
make generate-alberta-dist
which runs the steps 4.)-5.).
VI) 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.
Here we have some cases of operating systems (produced as output of the
script "config.guess"):
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) SuSE 9.2: We used MesaGL and a BLAS lib included in our
distribution. If MesaGL is not found, "configure" will also try "GL". The
alberta_util lib needed "-lg2c" to process FORTRAN code properly.
b) SuSE 10.0: Trouble with the FORTRAN compiler. Try running
F77=gfortran ../configure
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.
VII) Making rpm packages
========================
This is still an experimental feature. We habe included an alberta-2.0.spec
file adapted for SUSE LINUX 9.2. Using "rpmbuild -ba alberta-2.0.spec" will
process an "alberta-2.0.tar.gz" bundle in "/usr/src/packages/SOURCES". After
unpacking, configuring, building, and installing you will (hopefully) have
"alberta-2.0-1.i586.rpm" as well as "alberta-2.0-1.src.rpm".
The first package will install the libraries in "/usr/local/lib", headers in
"/usr/local/include", the programs in "usr/local/bin", and the demo package in
"/usr/local/share/alberta". The installation directories can be changed by
passing options to "rpm" (we have tried to build "relocatable" rpms).