CFD/hypre
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
fcc7b8aad5
hypre/docs_misc/dev_makefile.tex

406 lines
20 KiB
TeX
Raw Blame History

%==========================================================================
\chapter{The HYPRE Build System}
\label{The HYPRE Build System}
The \hypre{} build system relies on GNU Autoconf and a few related macro files (\file{*.m4}) to
create the \file{configure} script used to query each platform for values needed to properly build
the library. These values are substituted into the appropriate Makefiles then \file{make} is
run to compile and build the library.
When generated the \file{configure} script itself is in the \file{linear\_solvers} directory,
all of the other necessary files are in the \file{config} subdirectory. Although it is unlikely
that a developer will need to modify any of the scripts, those that may need changing are further
described below.
%==========================================================================
\section{Bootstrap Script}
\label{Bootstrap Script}
A Bourne shell script named \file{bootstrap}, is provided in the \file{config} subdirectory
to relieve developers of needing to know the required versions or constraints of the GNU
tools being used. \file{bootstrap} is run from the \file{linear\_solvers} directory
(\file{./config/bootstrap}) whenever changes are made to the macro (\file{*.m4}) files or
the \file{configure.in} script.
%==========================================================================
\section{Configure Script}
\label{Configure Script}
The GNU tool Autoconf reads a template file named \file{configure.in} and the M4 macro files,
which are customized for \hypre{}, to generate the \file{configure} script for automatically
configuring \hypre{}.
\file{configure} is run from the \file{linear\_solvers} directory. See the 'Configure and Make'
section for details on running \file{configure}.
%==========================================================================
\section{Makefile Requirements}
\label{Makefile Requirements}
There is only one Makefile, named \file{Makefile.config.in}, that is modified by running
\file{configure}. This file contains all of the values that are needed to build \hypre{}
which are defined by \file{configure}. Developers should not have to modify this file unless
new variables are defined in or needed from \file{configure}.
Each \hypre{} subdirectory contains an old-fashioned \file{Makefile} that includes
\file{Makefile.config} to access the needed values. These files can be edited as needed.
Whenever a developer adds a new subdirectory, they must add the new name to the top-level
\file{Makefile} as well as providing an appropriate \file{Makefile} in the subdirectory.
The \file{linear\_solvers} directory contains a sample Makefile, named \file{Makefile.sample},
that can be copied and edited for use in new subdirectories.
To build the entire \hypre{} library, \file{make} is run from the \file{linear\_solvers}
directory. To rebuild any given subdirectory, run \file{make} in that subdirectory alone.
See the 'Configure and Make' section for a description of \file{make} targets and execution details.
%==========================================================================
\section{Configure and Make}
\label{Configure and Make}
Now that all of the files are created/edited, \hypre{} is ready to be configured
and made for the host platform. The simplest method is to configure, compile and
install the libraries in \file{hypre/lib} and \file{hypre/include} directories, which is
accomplished by:
\begin{verbatim}
./configure
make
\end{verbatim}
Of course there are many options to \file{configure} and \file{make} targets to
customize such things as installation directories, compilers used, compile and
load flags, etc.
\file{configure} searches for and reports the system type being used for building
and executing, compilers being used, libraries being searched, option flags being set,
etc. When all of the searching is done a file named \file{config.status} is created
in the \file{linear\_solvers} directory. If there were errors while configuring a file
named \file{config.log} is left in the \file{linear\_solvers} directory when \file{configure}
terminates. Upon successful completion of \file{configure} the file \file{Makefile.config}
is created from its template \file{Makefile.config.in} and \hypre{} is ready to be made.
Executing \file{make}, with or without targets being specified, in the \file{linear\_solvers} directory
initiates compiling of all of the source code and building of the \hypre{} library.
When building HYPRE without the install target, the libraries and include files will be copied
into the default directories, \file{linear\_solvers/hypre/lib} and
\file{linear\_solvers/hypre/include}, respectively.
When building HYPRE using the install target, the libraries and include files will be copied
into the directories that the user specified in the options to \file{configure},
e.g. --prefix=/usr/apps. If none were specified the default directories are used,
\file{linear\_solvers/hypre/lib} and \file{linear\_solvers/hypre/include}.
%==========================================================================
\subsection{Configure Options}
\label{Configure Options}
\file{configure} has many options to allow the user to override and refine the
defaults for any system. The best way to find out what options are available is
to display the help package which also includes the usage information.
NOTE: when executing on an IBM platform \file{configure} must be executed under
the nopoe script (\file{./nopoe ./configure <option> ...<option>}) to force a single
task to be run on the log-in node.
The results of \file{./configure --help} when run on a local Linux platform are:
\begin{verbatim}
'configure' configures hypre 1.9.xx to adapt to many kinds of systems.
Usage: ./configure [OPTION] ... [VAR=VALUE]...
To assign environment variables (e.g. CC, CFLAGS ...), specify them as
VAR=VALUE. See below for descriptions of some of the useful variables.
Defaults for the options are specified in brackets.
Configuration:
-h, --help display this help and exit
--help=short display options specific to this package
--help=recursive display the short help of all the included packages
-V, --version display version information and exit
-q, --quiet, --silent do not print 'checking ...' messages
--cache-file=FILE cache test results in FILE [disabled]
-C, --config-cache alias for '--cache-file=config.cache'
-n --no-create do not create output files
--srcdir=DIR find the sources in DIR [configure dir or '..']
Installation Directories:
--prefix=PREFIX install architecture-independent files in PREFIX
[/home/hill66/linear_solvers/hypre]
--exec-prefix=EPREFIX install architecture-dependent files in EPREFIX
[PREFIX]
By default, 'make install' will install all files in
/home/hill66/linear_solvers/hypre/lib, /home/hill66/linear_solvers/hypre/bin, etc.
You can specify an installation prefix other than /home/hill/linear_solvers/hypre by using
the --prefix option; for instance --prefix=$HOME.
For fine tuning of the installation directories:
--bindir=DIR user executables [EPREFIX/bin]
--sbindir=DIR system admin executables [EPREFIX/sbin]
--libexecdir=DIR program executables [EPREFIX/libexec]
--datadir=DIR read-only architecture independent data [PREFIX/share]
--sysconfdir=DIR read-only single machine data [PREFIX/etc]
--sharedstatedir=DIR modifiable architecture independent data [PREFIX/com]
--localstatedir=DIR modifiable architecture dependent data [PREFIX/var]
--libdir=DIR object code libraries [EPREFIX/lib]
--includedir=DIR C header files [PREFIX/include]
--oldincludedir=DIR C header files for non GCC [/usr/include]
--infodir=DIR info documentation [PREFIX/info]
--mandir=DIR man documentation [PREFIX/man]
System Types:
--build=BUILD configure for building on BUILD [guessed]
--host=HOST cross-compile to build programs to run on HOST [BUILD]
Optional Features:
--disable-FEATURE do not include FEATURE (same as --enable-FEATURE=no)
--enable-FEATURE[=ARGS] include FEATURE [ARG=yes]
--enable-debug compile for debugging
--enable-shared build shared libraries [default=NO] (NOT Implemented)
Optional Packages:
--with-PACKAGE[=ARG] use PACKAGE [ARG=yes]
--without-PACKAGE do not use PACKAGE (same as --with-PACKAGE=no)
--with-LD=ARG Set linker to ARG. Environment variable 'LD' is overridden.
--with-LDFLAGS=ARG Set linker flags to ARG.
Environment variable 'LDFLAGS' is overridden.
--with-extra-incpath=PATH
Define extra include path, PATH is space delimited list of
directories.
--with-extra-ldpath=PATH
Define extra LD path, PATH is space delimited list of
directories.
--with-insure=FLAGS FLAGS are options to pass to insure,
e.g. -log-file=struct.insure -append-logfile=yes will send
output to the specified file. Defines gcc and g++ as the
C and C++ compilers unless they are already set by the user.
There is NO guarantee that insure exists on the machine.
--with-insure-to-file Forces insure output to a file named insure.log
Defines gcc and g++ as the C and C++ compilers unless they are
already set by the user.
There is NO guarantee that insure exists on the machine.
--with-purify=FLAGS FLAGS are options to pass to purify,
e.g. -log-file=struct.purify -append-logfile=yes will send
output to the specified file. Defines gcc and g++ as the
C and C++ compilers unless they are already set by the user.
There is NO guarantee that purify exists on the machine.
--with-purify-to-file Forces purify output to a file named purify.log
Defines gcc and g++ as the C and C++ compilers unless they are
already set by the user.
There is NO guarantee that purify exists on the machine.
--with-strict-checking
Compiles without MPI and tries to find a compiler that warns
of as many non-ANSI features as possible.
--with-MPI-include=DIR
User specifies that mpi.h is in DIR. The options
--with-MPI-include, --with-MPI-libs and
--with-MPI-lib-dirs MUST be used together.
--with-MPI-libs=LIBS LIBS is a space delimited list of library names needed
for MPI, e.g. <nsl socket mpi>. The options
--with-MPI-include, --with-MPI-libs and
--with-MPI-lib-dirs MUST be used together.
--with-MPI-lib-dirs=DIRS
DIRS is a space delimited list of directories containing
the libraries specified by --with-MPI-libs, e.g.
</usr/lib /usr/local/mpi/lib>. The options
--with-MPI-include, --with-MPI-libs and
--with-MPI-lib-dirs MUST be used together.
--with-MPI-flags=FLAGS
FLAGS is a space delimited list of whatever flags other
than -l and -L are needed to link with MPI libraries.
This option does NOT deactivate the auto-search for other
MPI information. It MAY be used with the other MPI options
or alone in conjunction with the automatic MPI search.
--with-blas-libs=LIBS LIBS is a space delimited list of library names needed
for blas. The options --with-blas-libs and
--with-blas-lib-dirs MUST be used together.
--with-blas-lib-dirs=DIRS
DIRS is a space delimited list of directories containing
the libraries specified by --with-blas-libs, e.g.
</usr/lib /usr/local/blas/lib>. The options --with-blas-libs
and --with-blas-lib-dirs MUST be used together.
--with-lapack-libs=LIBS
LIBS is a space delimited list of library names needed
for lapack. The options --with-lapack-libs and
--with-lapack-lib-dirs MUST be used together.
--with-lapack-lib-dirs=DIRS
DIRS is a space delimited list of directories containing
the libraries specified by --with-lapack-libs, e.g.
</usr/lib /usr/local/lapack/lib>. The options --with-lapack-libs
and --with-lapack-lib-dirs MUST be used together.
--with-fei-libs=LIBS
LIBS is a space delimited list of library names needed
for FEI. The options --with-fei-libs, --with-fei-lib-dirs and
--with-fei-inc-dirs MUST be used together.
--with-fei-lib-dirs=DIRS
DIRS is a space delimited list of directories containing
the libraries specified by --with-fei-libs, e.g.
</usr/lib /usr/local/fei/lib>. The options --with-fei-libs
--with-fei-lib-dirs and --with-fei-inc-dirs MUST be used together.
--with-fei-inc-dirs=DIRS
DIRS is a space delimited list of directories containing
the include files specified by --with-fei-libs, e.g.
</usr/include /usr/local/include>. The options --with-fei-libs
--with-fei-lib-dirs and --with-fei-inc-dirs MUST be used together.
--with-COMM_SIMPLE Do NOT use MPI derived data types. This option is automatically
selected for IBM platforms, it may be user-selected for others.
--with-timing use HYPRE timing routines
--with-openmp use OpenMP; may affect compiler choice; supported using guidec on
IBM and Compaq
--with-babel use babel
--with-mli use MLI
--with-MPI DEFAULT: compiles with MPI
--with-blas Find a system-provided BLAS library
--with-lapack Find a system-provided LAPACK library
Some influential environment variables:
CC C compiler command
CFLAGS C compiler flags
LDFLAGS linker flags, e.g. -L<lib dir> for libraries in non-standard directory
<lib dir>
CPPFLAGS C/C++ preprocessor flags, e.g. -I<include dir> for header files in
non-standard directory <include dir>
CPP C preprocessor
CXX C++ compiler command
CXXFLAGS C++ compiler flags
F77 Fortran 77 compiler command
FFLAGS Fortran 77 compiler flags
CXXCPP C++ preprocessor
Use these variables to override the choices made by 'configure' or to help
it find libraries and programs with non-standard names/locations.
Report issues and requests to hypre-support@llnl.gov.
\end{verbatim}
%==========================================================================
\subsubsection{Configure Execution and Sample Output}
\label{Configure Execution and Sample Output}
\begin{verbatim}
Usage: ./configure [OPTION] ... [VAR=VALUE]...
\end{verbatim}
Examples of using \file{configure} with options and variable settings. The user can mix
and match the options and variable settings as needed to satisfy their requirements.
\begin{verbatim}
./configure --with-openmp --enable-debug
./configure CC=mpiicc --with-babel
./configure --with-blas-lib="essl" --with-blas-lib-dirs="/usr/lib"
\end{verbatim}
The output from \file{configure} is several pages long. It reports the system type
being used for building and executing, compilers being used, libraries being searched,
option flags being set, etc.
The following is a very short sample of \file{configure} output.
\begin{verbatim}
./configure
checking build system type. . . i686-pc-linux-gnu
checking host system type. . . i686-pc-linux-gnu
checking for mpcc. . . no
checking for mpikcc. . . no
checking for mpicc. . . mpicc
checking for mpCC. . . no
checking for mpiKCC. . . no
checking for mpiCC. . . mpiCC
checking for mpxlf. . . no
checking for mpikf77. . . no
checking for mpif77. . . mpif77
checking whether the C compiler works. . . yes
checking for egrep. . . grep -E
checking for sys/types.h. . . yes
checking for float.h. . . yes
checking for dgemm_ in -lessl. . . no
.
.
.
configure: creating ./config.status
config.status: creating Makefile.config
config.status: creating HYPRE_config.h
config.status: HYPRE_config.h is unchanged
\end{verbatim}
%==========================================================================
\subsection{Make Targets}
\label{Make Targets}
The make step in building \hypre{} is where the compiling, loading and creation
of libraries occurs. Make has several options that are called targets. These include:
\begin{verbatim}
help prints the details of each target
all default target in all directories
compile the entire library
does NOT rebuild documentation
clean deletes all files from the current directory that are
created by building the library
distclean deletes all files from the current directory that are created
by configuring or building the library
install compile the source code, build the library and copy executables,
libraries, etc to the appropriate directories for user access
uninstall deletes all files that the install target created
tags runs etags to create a tags table
file is named TAGS and is saved in the top-level directory
test depends on the all target to be completed
removes existing temporary installation directories
creates temporary installation directories
copies all libHYPRE* and *.h files to the temporary locations
builds the test drivers; linking to the temporary locations to
simulate how application codes will link to HYPRE
\end{verbatim}
%==========================================================================
\subsubsection{Make Execution and Sample Output}
\label{Make Execution and Sample Output}
\begin{verbatim}
Usage: make [TARGET]
\end{verbatim}
Examples of using \file{make} with different targets. Only ONE target can be specified at a time.
\begin{verbatim}
make
make install
make test
\end{verbatim}
The execution of \file{make} creates several pages of output. The following is a brief
sample of the command \file{make}.
\begin{verbatim}
Output from make:
make[3]: Entering directory '/home/hill66/linear_solvers/krylov
mpicc -O2 -I.. -I./.. -I./../multivector -I./../utilities -DHAVE_CONFIG_H -c cgnr.c
mpicc -O2 -I.. -I./.. -I./../multivector -I./../utilities -DHAVE_CONFIG_H -c gmres.c
mpicc -O2 -I.. -I./.. -I./../multivector -I./../utilities -DHAVE_CONFIG_H -c pcg.c
mpicc -O2 -I.. -I./.. -I./../multivector -I./../utilities -DHAVE_CONFIG_H -c HYPRE_lobpcg.c
Building libHYPRE_krylov.a ...
ar -rcu libHYPRE_krylov.a cngr.o gmres.o pcg.o HYPRE_lobpcg.o
ranlib libHYPRE_krylov.a
cp -fp ./krylov.h /home/hill66/linear_solvers/hypre/include
cp -fp ./*lobpcg*.h /home/hill66/linear_solvers/hypre/include
cp -fp libHYPRE* /home/hill66/linear_solvers/hypre/lib
make[3]: Leaving directory '/home/hill66/linear_solvers/krylov
\end{verbatim}
Reference in New Issue View Git Blame Copy Permalink