446 lines
17 KiB
TeX
446 lines
17 KiB
TeX
%==========================================================================
|
|
\chapter{Creating and HYPRE Release}
|
|
\label{Creating and HYPRE Release}
|
|
|
|
Making a \hypre{} release available to the user community involves creating a
|
|
distribution tar file, putting it on the \hypre{} download page, and sending an
|
|
announcement to the appropriate email list. Formerly, we also supported the
|
|
installation of the library on the Livermore Computing (LC) platforms. In case
|
|
we go back to providing support sometime in the future, the documentation for
|
|
installing the library remains below.
|
|
|
|
General and beta releases are installed on all supported LC platforms. While
|
|
alpha releases are installed {\bf only} on the CASC cluster. Each release is
|
|
configured and built with different options which results in the creation of
|
|
subdirectories as defined below:
|
|
\begin{itemize}
|
|
\item optimized -- stored in lib and include
|
|
\item optimized and debug -- stored in debug/lib and debug/include
|
|
|
|
\item serial -- stored in serial/lib and serial/include
|
|
\item serial and debug -- stored in serial/debug/lib and serial/debug/include
|
|
|
|
\item threads -- stored in threads/lib and threads/include
|
|
\item threads and debug -- stored in threads/debug/lib and threads/debug/include
|
|
\end{itemize}
|
|
|
|
%==========================================================================
|
|
\section{Scripts}
|
|
\label{Scripts}
|
|
|
|
There are three Korn shell scripts \file{mkdist}, \file{mkdistlinks} and
|
|
\file{mklibs} that ease the task of building and installing \hypre{} on most
|
|
platforms. These scripts reside in the \file{tools} subdirectory of the
|
|
\hypre{} repository or in the root directory on specific platforms.
|
|
|
|
%==========================================================================
|
|
\subsection{mkdist}
|
|
\label{mkdist}
|
|
|
|
The distribution tar file is created with the \file{mkdist} script. The
|
|
\file{mkdist} script extracts the requested version from the repository,
|
|
reorganizes the file structure, builds the documentation and creates the
|
|
distribution tar file named \file{hypre-M.nn.rr.tar.gz}. Use the command
|
|
\kbd{mkdist -help} to get usage information.
|
|
|
|
%==========================================================================
|
|
\subsection{mkdistlinks}
|
|
\label{mkdistlinks}
|
|
|
|
The \file{mkdistlinks} script creates symbolic links from the \hypre{}
|
|
distribution tar file to subdirectories that are defined within this script.
|
|
The directory list only needs to be updated when new classes of platforms are
|
|
added.
|
|
|
|
\begin{verbatim}
|
|
Usage: ./mkdistlinks hypre-M.mm.rr.tar.gz
|
|
where:
|
|
hypre-M.mm.rr.tar.gz distribution tar file created by mkdist
|
|
\end{verbatim}
|
|
|
|
%==========================================================================
|
|
\subsection{mklibs}
|
|
\label{mklibs}
|
|
|
|
The \file{mklibs} script generates the various versions of the library
|
|
(optimized, debug, serial, threaded) and stores them in the appropriate
|
|
subdirectories. Optionally, it will symbolically link to the
|
|
\file{/usr/apps/hypre} directory. The \file{mklibs} script untars the
|
|
distribution, resulting in a new directory named \file{hypre-M.mm.rr} which
|
|
contains the \file{docs} and \file{src} subdirectories as well as the
|
|
\file{CHANGELOG} and other relevant files. Use the command \kbd{mklibs -help}
|
|
to get usage information.
|
|
|
|
There are two specialized versions of \file{mklibs}:
|
|
\begin{itemize}
|
|
\item \file{mklibs.aix} creates 32 and 64 bit libraries on AIX pltforms
|
|
\item \file{mklibs.babel} adds --with-babel to each of the installations
|
|
\end{itemize}
|
|
|
|
%==========================================================================
|
|
\section{Creating a Distribution Tar File}
|
|
\label{Creating a Distribution Tar File}
|
|
|
|
The distribution tar file is created on a local CASC platform. The following
|
|
steps detail the actions to be taken and provide examples where appropriate.
|
|
Prior to executing these steps, the release number will be assigned by the
|
|
project team. In the examples below, M-mm-rr is a place-holder for the actual
|
|
release number, which may or may not have an 'a' or 'b' appended, depending on
|
|
the type of release being created.
|
|
|
|
\begin{enumerate}
|
|
\item Ensure that the \code{CVSROOT} environment variable is set to point to the
|
|
location of the CASC repository \code{/home/casc/repository} (you will save
|
|
yourself more trouble than you think by doing this first).
|
|
\item Retrieve the latest version of \hypre{} from the CVS repository
|
|
\begin{verbatim}
|
|
cvs checkout linear_solvers
|
|
\end{verbatim}
|
|
\item In the \file{releases} directory, copy the appropriate \file{checklist_*}
|
|
file to a new file (follow the naming convention already started) and follow the
|
|
steps listed within. Several of the steps are replicated here.
|
|
\item In the \file{config/configure.in} file, change the release version number
|
|
and date, i.e., change
|
|
\begin{verbatim}
|
|
m4_define(HYPRE_VERSION, 1.9.0b)
|
|
m4_define(HYPRE_DATE, 2005/02/24)
|
|
\end{verbatim}
|
|
\item From the root directory, run the \file{config/bootstrap} script to create
|
|
a new \file{configure} script
|
|
\begin{verbatim}
|
|
./config/bootstrap
|
|
\end{verbatim}
|
|
\item Commit new \file{configure} and \file{configure.in} files to repository
|
|
\begin{verbatim}
|
|
cvs commit
|
|
\end{verbatim}
|
|
\item Tag the repository with this release number (for general releases, add the
|
|
\kbd{-b} option after \kbd{rtag} to create a new branch)
|
|
\begin{verbatim}
|
|
cvs rtag VM-mm-rr linear_solvers
|
|
\end{verbatim}
|
|
\item Create the distribution tar file by running the \file{tools/mkdist}
|
|
script. Output are two compressed tar files named \file{hypre-M.mm.rr.tar.gz}
|
|
and \file{hypre-M.mm.rr-babel.tar.gz}. This may be run from within any
|
|
directory, as long as the latest version of the script is being used (the
|
|
following is being run from the root directory).
|
|
\begin{verbatim}
|
|
./tools/mkdist VM-mm-rr
|
|
\end{verbatim}
|
|
\item Test the release tar files with the \file{testdist.sh} script.
|
|
\item Copy the tar file to /usr/casc/hypre on the local system
|
|
\begin{verbatim}
|
|
cp hypre-M.mm.rr.tar.gz /usr/casc/hypre
|
|
\end{verbatim}
|
|
\item Put the release on the download page.
|
|
\end{enumerate}
|
|
|
|
%==========================================================================
|
|
\section{Installing a Distribution on the CASC Cluster}
|
|
\label{Installing a Distribution on the CASC Cluster}
|
|
|
|
On the CASC cluster the root directory for \hypre{} is \file{/usr/casc/hypre}. The
|
|
subdirectory is \file{i686-pc-linux-gnu}. The following procedure will build the
|
|
library with its options and store in the appropriate directories.
|
|
|
|
\begin{enumerate}
|
|
\item Move to the /usr/casc/hypre directory
|
|
\begin{verbatim}
|
|
Example: cd /usr/casc/hypre
|
|
\end{verbatim}
|
|
\item Create symbolic links to the tar file by running the \file{mkdistlinks} script
|
|
\begin{verbatim}
|
|
Example: ./mkdistlinks hypre-M.mm.rr.tar.gz
|
|
\end{verbatim}
|
|
\item Move to the CASC cluster subdirectory; i686-pc-linux-gnu
|
|
\begin{verbatim}
|
|
Example: cd i686-pc-linux-gnu
|
|
\end{verbatim}
|
|
\item Build and install the library by runnning the \file{mklibs} script; which is
|
|
located in the \file{/usr/casc/hypre} directory.
|
|
The arguments -g (general), -b (beta) or -a (alpha) indicate the type of
|
|
release being generated. If the install argument is included the
|
|
symbolic links will be created automatically.
|
|
\begin{verbatim}
|
|
Example: ../mklibs <-g | -b | -a> hypre-M.mm.rr.tar.gz <install>
|
|
\end{verbatim}
|
|
\end{enumerate}
|
|
|
|
%==========================================================================
|
|
\section{Installing a Distribution on LC Platforms}
|
|
\label{Installing a Distribution on LC Platforms}
|
|
|
|
On all of the supported LC platforms, the root directory for \hypre{} is
|
|
\file{/usr/gapps/hypre}. Under the root are subdirectories for each class
|
|
of machines identified by the LC defined environment variable, SYS\_TYPE.
|
|
The following table shows the SYS\_TYPE values for supported LC open (OCF)
|
|
and secure (SCF) platforms as of April 2005.
|
|
|
|
\begin{verbatim}
|
|
SYS_TYPE OCF SCF
|
|
aix_5_64 --- tempest
|
|
aix_5_ll frost white, ice
|
|
aix_5_64_fed newberg uv, um
|
|
tru64_5 gps sc
|
|
sles_9_ppc64 bgl ---
|
|
chaos_3_x86 ilx ace
|
|
chaos_3_x86_elan3 pengra, alc, mcr, adelie, emperor,
|
|
pvc, bigdev lilac, gviz
|
|
chaos_3_x64_elan4 thunder cub
|
|
\end{verbatim}
|
|
|
|
To relieve the user of needing to know the SYS\_TYPE on each platform, the path
|
|
\file{/usr/apps/hypre} will be symbolically linked to the appropriate subdirectory
|
|
on each platform by the development team. The command to create the link is:
|
|
\begin{verbatim}
|
|
ln -s /usr/gapps/hypre/<SYS_TYPE> /usr/apps/hypre
|
|
where the actual value of SYS_TYPE is substituted for <SYS_TYPE>.
|
|
\end{verbatim}
|
|
|
|
%==========================================================================
|
|
\subsection{Open Computing Facility (OCF) Platforms}
|
|
\label{Open Computing Facility (OCF) Platforms}
|
|
|
|
Before the \hypre{} library can be built on an OCF platform it needs to be
|
|
copied from the CASC cluster. This can be done from any CASC cluster directory
|
|
in which \file{hypre-M.mm.rr.tar.gz} exists by using the command (host is any OCF
|
|
platform):
|
|
\begin{verbatim}
|
|
scp hypre-M.mm.rr.tar.gz host:/usr/gapps/hypre
|
|
\end{verbatim}
|
|
|
|
When the distribution tar file has been successfully copied, create the symbolic
|
|
links to the tar file. This only needs to be done once for all platforms.
|
|
|
|
\begin{enumerate}
|
|
\item Move to the \file{/usr/gapps/hypre} directory
|
|
\begin{verbatim}
|
|
Example: cd /usr/gapps/hypre
|
|
\end{verbatim}
|
|
\item Create symbolic links to the tar file by running the \file{mkdistlinks} script
|
|
\begin{verbatim}
|
|
Example: ./mkdistlinks hypre-M.mm.rr.tar.gz
|
|
\end{verbatim}
|
|
\end{enumerate}
|
|
|
|
The procedure below MUST be repeated for each class of platforms on which \hypre{} is
|
|
to be installed.
|
|
|
|
\begin{enumerate}
|
|
\item If not already in the \file{/usr/gapps/hypre} directory; move to it
|
|
\begin{verbatim}
|
|
Example: cd /usr/gapps/hypre
|
|
\end{verbatim}
|
|
\item Move to the subdirectory for this platform, identified by SYS\_TYPE
|
|
\begin{verbatim}
|
|
Example: cd chaos_3_ia32_elan3
|
|
\end{verbatim}
|
|
\item Build and install the library by runnning the \file{mklibs} script; which is
|
|
located in the \file{/usr/gapps/hypre} directory.
|
|
The arguments -g (general) or -b (beta) indicate the type of release being
|
|
generated. If the install argument is included, the symbolic links will
|
|
be created automatically.
|
|
\begin{verbatim}
|
|
Example: ../mklibs <-g | -b> hypre-M.mm.rr.tar.gz <install>
|
|
\end{verbatim}
|
|
\end{enumerate}
|
|
|
|
%==========================================================================
|
|
\subsection{Secure Computing Facility (SCF) Platforms}
|
|
\label{Secure Computing Facility (SCF) Platforms}
|
|
|
|
Before the \hypre{} library can be built on an SCF platform it needs to be
|
|
copied from an OCF platform. This is done through the FIS utility by logging
|
|
onto an OCF platform, running FTP to connect to FIS, sending the file to the SCF,
|
|
logging out of OCF and logging into an SCF platform after a few hours have elapsed.
|
|
From an SCF platform again run FTP to extract the file from FIS and continue as
|
|
described below.
|
|
\begin{verbatim}
|
|
Example: On OCF: ftp fis
|
|
cd TO
|
|
put hypre-M.mm.rr.tar.gz
|
|
quit
|
|
\end{verbatim}
|
|
|
|
\begin{verbatim}
|
|
Example: On SCF: ftp fis
|
|
cd FROM
|
|
get hypre-M.mm.rr.tar.gz
|
|
quit
|
|
\end{verbatim}
|
|
|
|
When the distribution tar file has been successfully copied, create the symbolic
|
|
links to the tar file. This only needs to be done once for all platforms.
|
|
|
|
\begin{enumerate}
|
|
\item Move to the \file{/usr/gapps/hypre} directory
|
|
\begin{verbatim}
|
|
Example: cd /usr/gapps/hypre
|
|
\end{verbatim}
|
|
\item Create symbolic links to the tar file by running the \file{mkdistlinks} script
|
|
\begin{verbatim}
|
|
Example: ./mkdistlinks hypre-M.mm.rr.tar.gz
|
|
\end{verbatim}
|
|
\end{enumerate}
|
|
|
|
The procedure below MUST be repeated for each class of platforms on which \hypre{} is
|
|
to be installed.
|
|
|
|
\begin{enumerate}
|
|
\item If not already in the \file{/usr/gapps/hypre} directory; move to it
|
|
\begin{verbatim}
|
|
Example: cd /usr/gapps/hypre
|
|
\end{verbatim}
|
|
\item Move to the subdirectory for this platform, identified by SYS\_TYPE
|
|
\begin{verbatim}
|
|
Example: cd chaos_3_ia32_elan3
|
|
\end{verbatim}
|
|
\item Build and install the library by runnning the \file{mklibs} script; which is
|
|
located in the \file{/usr/gapps/hypre} directory.
|
|
The arguments -g (general) or -b (beta) indicate the type of release being
|
|
generated. If the install argument is included, the symbolic links will
|
|
be created automatically.
|
|
\begin{verbatim}
|
|
Example: ../mklibs <-g | -b> hypre-M.mm.rr.tar.gz <install>
|
|
\end{verbatim}
|
|
\end{enumerate}
|
|
|
|
%==========================================================================
|
|
\section{Example of Creating and Installing a Beta Release}
|
|
\label{Example of Creating and Installing a Beta Release}
|
|
|
|
In the example, the version number, machine names and user names are for illustration
|
|
purposes only; the specific values may differ. Each step is separated by a blank line.
|
|
Output from some steps is shown in abbreviated form immediately below the command.
|
|
|
|
On a local CASC platform:
|
|
\begin{verbatim}
|
|
1. cd /home/hill66
|
|
|
|
2. cvs checkout linear_solvers
|
|
U linear_solvers/CHANGELOG
|
|
U linear_solvers/COPYRIGHT_and_DISCLAIMER
|
|
. . .
|
|
U linear_solvers/utilities/utilities.h
|
|
U linear_solvers/utilities/version
|
|
|
|
3. cd linear_solvers/config
|
|
|
|
4. vi configure.in
|
|
<change values in m4_define(HYPRE_*) statements>
|
|
quit
|
|
|
|
5. ./config/bootstrap
|
|
|
|
6. cvs commit
|
|
Update configure files for release 1.90b
|
|
|
|
7. cvs rtag V1-9-0b linear_solvers
|
|
|
|
8. ./tools/mkdist V1-9-0b
|
|
U linear_solvers/CHANGELOG
|
|
U linear_solvers/COPYRIGHT_and_DISCLAIMER
|
|
. . .
|
|
U linear_solvers/utilities/utilities.h
|
|
U linear_solvers/utilities/version
|
|
checking the hostname... tux149
|
|
checking the architecture... linux
|
|
. . .
|
|
creating hypre-1.9.0b.tar file ...
|
|
|
|
9. cp hypre-1.9.0b.tar.gz /usr/casc/hypre
|
|
|
|
10. cd /usr/casc/hypre
|
|
|
|
11. ./mkdistlinks hypre-1.9.0b.tar.gz
|
|
lrwxrwxrwx 1 hil66 hypre 22 Apr 13 07:32 alphaev68-dec-osf5.1/hypre-1.9.0b.tar.gz -> ../hypre-1.9.0b.tar.gz
|
|
lrwxrwxrwx 1 hil66 hypre 22 Apr 13 07:32 i686-pc-linux-gnu/hypre-1.9.0b.tar.gz -> ../hypre-1.9.0b.tar.gz
|
|
lrwxrwxrwx 1 hil66 hypre 22 Apr 13 07:32 powerpc-ibm-aix5.2.0.0/hypre-1.9.0b.tar.gz -> ../hypre-1.9.0b.tar.gz
|
|
lrwxrwxrwx 1 hil66 hypre 22 Apr 13 07:32 chaos_3_ia32_elan3/hypre-1.9.0b.tar.gz -> ../hypre-1.9.0b.tar.gz
|
|
|
|
12. cd i686-pc-linux-gnu
|
|
|
|
13. ../mklibs -b hypre-1.9.0b.tar.gz install
|
|
checking the hostname... blue
|
|
checking the architecture... aix
|
|
. . .
|
|
Cleaning FEI_mv ...
|
|
Cleaning test ...
|
|
\end{verbatim}
|
|
The build and installation is now complete on the CASC cluster.
|
|
|
|
Next copy the tar file to an OCF platform (mcr in this example).
|
|
\begin{verbatim}
|
|
|
|
14. scp hypre-1.9.0b.tar.gz mcr:/usr/gapps/hypre
|
|
|
|
\end{verbatim}
|
|
|
|
Now log off the CASC cluster and into an OCF platform (mcr in this example) to build and
|
|
install \hypre{}.
|
|
\begin{verbatim}
|
|
15. ssh mcr
|
|
16. cd /usr/gapps/hypre
|
|
|
|
17. ./mkdistlinks hypre-1.9.0b.tar.gz
|
|
lrwxrwxrwx 1 hil66 hypre 22 Apr 13 07:32 alphaev68-dec-osf5.1/hypre-1.9.0b.tar.gz -> ../hypre-1.9.0b.tar.gz
|
|
lrwxrwxrwx 1 hil66 hypre 22 Apr 13 07:32 powerpc-ibm-aix5.2.0.0/hypre-1.9.0b.tar.gz -> ../hypre-1.9.0b.tar.gz
|
|
lrwxrwxrwx 1 hil66 hypre 22 Apr 13 07:32 chaos_3_ia32_elan3/hypre-1.9.0b.tar.gz -> ../hypre-1.9.0b.tar.gz
|
|
|
|
18. cd chaos_3_ia32_elan3
|
|
|
|
19. ../mklibs -b hypre-1.9.0b.tar.gz install
|
|
checking the hostname... blue
|
|
checking the architecture... aix
|
|
. . .
|
|
Cleaning FEI_mv ...
|
|
Cleaning test ...
|
|
\end{verbatim}
|
|
The build and installation is now complete on one OCF class of machines. For each of the
|
|
remaining classes of OCF platforms, log-in, cd to /usr/apps/hypre/<SYS\_TYPE> and repeat
|
|
step 19.
|
|
|
|
Next copy the tar file to an SCF platform (adelie in this example).
|
|
\begin{verbatim}
|
|
20. ftp fis
|
|
. . .
|
|
cd TO
|
|
put hypre-1.9.0b.tar.gz
|
|
quit
|
|
\end{verbatim}
|
|
|
|
Now log off the OCF platform and into an SCF platform (adelie in this example) to retrieve
|
|
the tar file.
|
|
\begin{verbatim}
|
|
21. ssh adelie
|
|
|
|
22. ftp fis
|
|
. . .
|
|
cd FROM
|
|
get hypre-1.9.0b.tar.gz
|
|
quit
|
|
\end{verbatim}
|
|
|
|
Now build and install \hypre{} on the SCF platform (adelie in this example).
|
|
\begin{verbatim}
|
|
|
|
23. cd /usr/gapps/hypre
|
|
|
|
24. ./mkdistlinks hypre-1.9.0b.tar.gz
|
|
lrwxrwxrwx 1 hil66 hypre 22 Apr 13 07:32 alphaev68-dec-osf5.1/hypre-1.9.0b.tar.gz -> ../hypre-1.9.0b.tar.gz
|
|
lrwxrwxrwx 1 hil66 hypre 22 Apr 13 07:32 powerpc-ibm-aix5.2.0.0/hypre-1.9.0b.tar.gz -> ../hypre-1.9.0b.tar.gz
|
|
lrwxrwxrwx 1 hil66 hypre 22 Apr 13 07:32 chaos_3_ia32_elan3/hypre-1.9.0b.tar.gz -> ../hypre-1.9.0b.tar.gz
|
|
|
|
25. cd chaos_3_ia32_elan3
|
|
|
|
26. ../mklibs -b hypre-1.9.0b.tar.gz install
|
|
checking the hostname... blue
|
|
checking the architecture... aix
|
|
. . .
|
|
Cleaning FEI_mv ...
|
|
Cleaning test ...
|
|
\end{verbatim}
|
|
The build and installation is now complete on one SCF class of machines. For each of the
|
|
remaining classes of SCF platforms, log-in, cd to /usr/gapps/hypre/<SYS\_TYPE> and repeat
|
|
step 26.
|