
Help.makefile_macros

This file provides help to generate a makefile_macros file
for a machine on which the ABINIT package has not yet been ported.

See the latest ~ABINIT/Infos/install_v*.*html file to install 
the ABINIT package, to generate 
the executable and to make the tests.
See the file ~ABINIT/Infos/new_user_guide.html, 
for an introduction to the abinit package. 
See the file ~ABINIT/Infos/abinis_help.html for
learning how to use the code. 

Any comment of suggestion to improve the makefile_macros file will be welcome !
Contact the ABINIT group.

Copyright (C) 1999-2005 ABINIT group (XG,DCA) 
This file is distributed under the terms of the
GNU General Public License, see ~ABINIT/Infos/copyright
or http://www.gnu.org/copyleft/gpl.txt .
For the initials of contributors, see ~ABINIT/Infos/contributors .

*******************************************************************

1. Location and use of the makefile_macros file.
2. Content of the makefile_macros file, for the sequential version 
  or OpenMP-parallel versions of ABINIT.
3. Content of the makefile_macros file, for the MPI-parallel version of ABINIT.
4. NetCDF related content of makefile_macros
5. Structure of Makefile, makemake, tmp_makefile .
 
*******************************************************************

1. Location and use of the makefile_macros file.

In order to install the code for the first time on a machine, a 
specific machine-dependent file, giving the location of compilers
and other important informations, must be produced.

Its suggested name is :
makefile_macros.name_of_the_machine
where 'name_of_the_machine' is to be replaced by the specific name of the
machine.
Its suggested location should be in a subdirectory of the subdirectory
Machine_dept_files
of the main ABINIT directory. There are already many subdirectories of the
Machine_dept_files directory,
whose name emphasize the machine's construction, and an eventual
additional characteristics :
DEC , HP , IBM ...
In these subdirectories, many examples of makefile_macros.xxx files 
can be found.

In view of the use by the make command, and if the organisation suggested above
has been followed, a symbolic link (or a copy) must be created
from the main ABINIT directory to the specific file. For example :
ln -s Machine_dept_files/constructor/makefile_macros.name_of_the_machine makefile_macros 

*******************************************************************
 
2. Content of the makefile_macros file, for the sequential version of ABINIT,
 and the OpenMP-parallel version of ABINIT.

For the installation of the sequential version of ABINIT or the
OpenMP-parallel version of ABINIT,
the makefile_macros file should specify the content of the different 
variables, as described below. You should have a look at an existing 
makefile_macros file, while reading the present description.
A few of these information can be found by using the 'which' command, like
 which cpp
or
 which perl

Note that the name of the ~ABINIT directory will
be passed down in $(DIR) from the makemake scripts.
The name of the directory where the binaries have to
be placed will be passed in $(BINDIR). Usually, $(DIR)
and $(BINDIR) refer to the same directory.
$(BINDIR) is generated thanks to the  make bindir
command. The latter create a file tmp_indir in the
main directory. you might modify it by hand if you want.

The info on the libraries is also passed down :
the NumRecip and Lapack archive locations are already defined 
in the variables LAPACK_A and NUMRECIP_A  .

MACHINE      The machine type, to be chosen between the following possibilities:
             sgi, ibm, hp, P6, dec_alpha, vpp, 
             sun, T3E, nec, mac, sr8k (Hitachi) . 
             A new type might be created, if needed.
             This information is used in the following routines 
             of the ~ABINIT/Src_0basis directory : herald.f, timein.f .
             It might also be used in other routines, for optimisation,
             or for getting rid of machine-dependent problems.
             Here is a list of example routines that you might look at :
             ccfft.f, indefo.f, nonlop.f, orthon.f, sincos.f, sphere.f . 
             DEFAULT : null string 
              (will not work, MACHINE must be provided !)

FC           The Fortran compiler
             For example : FC=xlf90
             DEFAULT : null string 
              (will not work, FC must be provided !)

FFLAGS       The options and flags for the compilation of most of the
             routines of ABINIT (F90 with FREE format).
             Typical use in the make procedure :  $(FC) $(FFLAGS) -c ...
             For example : FFLAGS=-Mextend -Mfree -O2 -Mserial
             DEFAULT : null string  
              (usually, FFLAGS is needed)

MAIN_ROUTINE_FFLAGS
             Specific option and flags for the compilation of the
             main routines (abinit.f, newsp.f, ... - F90 with FREE format).
             Typical use in the make procedure :
             $(FC) $(MAIN_ROUTINE_FFLAGS) $(FFLAGS) -c ... 
             DEFAULT : null string  
              (OK for most situations)

FFLAGS_directoryname (e.g. FFLAGS_Src_2nonlocal)
             Specific option and flags for the compilation of
             a selected directory. 
             WARNING : does not work for
             - Src_main (see MAIN_ROUTINE_FFLAGS), 
             - the libs directories, 
             - Src_0basis and Src_8seqpar (it works
              for the sequential version of the routines of
              these directories ; in the parallel case, FFLAGS_PAR
              is used)
             Typical use in the make procedure :
             $(FC) $(FFLAGS_directoryname) -c ...
             One can use more than one such specification :
             FFLAGS= -O0
             FFLAGS_Src_2nonlocal= -O3
             FFLAGS_Src_2ffts= -O3
             DEFAULT : FFLAGS_directoryname = $(FFLAGS)
              (presently, the default is used in all cases)

             
FC_LIBS      The Fortran compiler, for the specific case of the
             routines of the NumRecip, Lapack and BLAS libraries.
             (F90 with FIXED format)
             DEFAULT : FC_LIBS= $(FC)  
              (presently, this default is OK for all machines)

FFLAGS_LIBS  The options and flags for the compilation of the routines
             of the NumRecip, Lapack and BLAS libraries
             (F90 with FIXED format)
             Typical use in the make procedure : $(FC_LIBS) $(FFLAGS_LIBS) -c ...
             DEFAULT : $(FFLAGS_LIBS)=$(FFLAGS)
              (OK for most situations)

FLINK        The option and flags for the link operation.
             Typical use in the make procedure :  $(FC) $(FLINK) -o ... 
             DEFAULT : null string 
              (OK for most situations)

AR_COMMAND   The archive command, to which the option -rv is added 
             automatically. Used in the makearch script.
             Usually AR_COMMAND= ar 
             For the 64-bit IBM architecture, it was needed to use  
             AR_COMMAND= ar -X64
             DEFAULT :  AR_COMMAND= ar 
              (OK for most situations)

CPP          The C preprocessor (see ~ABINIT/Infos/Notes_for_coding/use_cpp )
             DEFAULT : null string 
              (will not work, CPP must be provided !)

CPP_FLAGS    Eventual additional flags for the C preprocessor
             These will be used to preprocess the Fortran sources.
             Typically :
             CPP_FLAGS=-P
             or 
             CPP_FLAGS=-P -traditional

             The flag -Dnolib  suppress the use of machine-vendor
             libraries, like DXML for DEC machines, or VECLIB for HP,
             of ESSL for IBM, and use sources provided with the code
             (in which case, BLAS_A must be defined below) :
             CPP_FLAGS=-Dnolib -P

             Another flag is needed for preprocessing leading to the OpenMP parallel
             versions : -DOPENMP . See ~ABINIT/Infos/paral_use .
             CPP_FLAGS=-DOPENMP -P

             The flag -DCHGSTDIO changes the standard I/Os
             They are now the files ab.files (list of files or roots)
             and log.
             CPP_FLAGS=-DCHGSTDIO -P

             The flag -DCONTRACT keeps the "design-by-contract" sections of routines,
             that check the values of arguments of other routines.
             In production mode, they are not needed, while
             they are recommended in the development phase. They
             slow down the execution of the code, although not by much.

             The flag -DXMLF90 keeps the reading of XML pseudopotentials.
             One need to have the XMLf90 library compiled ("make xmlf90").
             One need also to define the location of the corresponding archive (see the AR_XMLF90 variable).

             Flags like -DTEST_PAW or -DTEST_AIM might be used to 
             keep a number of testing subroutines, as designed by developers.
             Typically :
             CPP_FLAGS=-DTEST_XXX -P -traditional
             where XXX is to be replaced by the adequate string.

             The flag -DHAVE_NANOQUANTAXC keeps the call to the NANOQUANTA libXC

             Note the typical use in the make procedure :  
             $(CPP) $(CPP_OPTS) $(CPP_FLAGS) ...
             where CPP_OPTS is defined in the makemake scripts:
             CPP_OPTS=-C -D\$(MACHINE)

             DEFAULT : CPP_FLAGS=-P
              (OK for most situations)

RM_CPP       Can take two values : 'yes' or 'no' : after the C preprocessing, 
             the code will remove or keep the cpp preprocessed source files.
             The default is 'yes'. 
             To keep the cpp files, indicate (blanks are relevant) :
             RM_CPP= no
             Otherwise, these files are removed automatically, to save space.
             In order to remove all cpp preprocessed files, after debugging, 
             one should issue, in the ~ABINIT directory : 
             make clean_debug
             DEFAULT : RM_CPP= yes
              (OK if no debugging)

CC           The C compiler
             This is needed only if the version of ABINIT for this machine
             needs to call a routine written in C (see the description of the
             MACHINE_DEP_C_SEQ_SUBS_LIST and MACHINE_DEP_C_PAR_SUBS_LIST
             variables).
             DEFAULT : null string 
              (will not work, unless no C routine is needed)

CFLAGS       Eventual flags for the C compiler
             DEFAULT : null string 

PERL         The location of perl 
             'perl' scripts are used to make the code as well as
             to run it and analyse automatically the results
             of tests. They need the location of perl to be run. Actually,
             this location will be copied at the beginning of the perl scripts.
             For example, in ~ABINIT/Test_fast, the file 'Run' will be created
             from 'Run.pl' thanks to 'make perl'. 
             Perl is available at http://www.perl.org .
             DEFAULT : null string 
              (many features will not work with this default !)

MACHINE_DEP_F_SEQ_SUBS_LIST
MACHINE_DEP_C_SEQ_SUBS_LIST
             Lists of machine-dependent Fortran or C routines.
             Presently, no machine need an additional Fortran
             routine, while a C CPU timer must usually be provided 
             here (can be etime.c or cclock.c). Note that in the name
             of the routines, .c or .f must be replaced by .o in these lists.
             DEFAULT : null string 

BLAS         If one wants to use the blas sources
             provided with ABINIT, then BLAS should be
             BLAS = Lib_blas/blas.a
             Otherwise, BLAS should be a null string: 
             BLAS = 
             while the necessary information about the vendor-provided
             blas library must be provided in the LIBS variable.
             DEFAULT : BLAS = Lib_blas/blas.a

LAPACK       If one wants to use the blas sources
             provided with ABINIT, then LAPACK should be 
             LAPACK = Lib_lapack/lapack.a
             Otherwise, LAPACK should be a null string: 
             LAPACK =
             while the necessary information about the vendor-provided
             lapack library must be provided in the LIBS variable.
             DEFAULT : LAPACK = Lib_lapack/lapack.a

LIBS         String of character to be used at the end of the
             link command. It must mention all the libraries to be used.
             When the library provided with ABINIT are to be used, 
             LIBS should be :
             LIBS = $(LAPACK) $(BLAS)
             Example with a vendor-provided blas :
             LIBS = $(LAPACK) -lblas
             Example with the FFTW library, with a variable FFTW is defined :
             FFTW= -L/applis/cmf/imo/fftw/lib -ldfftw_threads -ldfftw -lpthread
             LIBS= $(LAPACK) $(BLAS) $(FFTW)
             Typical use in the make procedure : mentioned at the end of the
             $(FC) $(FLINK) ... command. 
             DEFAULT : LIBS = $(LAPACK) $(BLAS)

AR_XMLF90    Location of the XMLf90 archive, if the preprocessing option -DXMLF90
             is activated. Not needed if this option is not activated. 
             The typical value is
             AR_XMLF90= $(XMLF90)
             DEFAULT : AR_XMLF90=

After these definitions, it is possible to add other definitions
or command lines in the makefile_macros file. 
For example, it appears that for the DEC machines, a header must be included
in some routines. This is accomplished thanks to the call to a task
MACHINE_DEP_LIB_HDR in the makemake script, defined in the corresponding
makefile_macros files for the DEC machines.

*******************************************************************

3. Content of the makefile_macros file, for the MPI-parallel version of ABINIT.      

The following variables are needed ONLY for the preparation
of the abinip (parallel abinit) binaries.

CPP_MPI      Additional flag for the C preprocessor, needed to activate
             selected parts of abinit, leading to MPI-parallelisation.

             To activate the parallelism one must specify -DMPI or -DMPI_FFT . 
             In the future, both will be permitted together. 
             -DMPI is the standard parallelization flag for ABINIT.
             -DMPI_FFT is presently under development (no speed up).

             To activate the possibility to use the MPI I/O library,
             the flag -DMPIO must be specified, in addition of either
             -DMPI or -DMPI_FFT

             Will be used as $(CPP) $(CPP_OPTS) $(CPP_FLAGS) $(CPP_MPI) ...
             For example :
             CPP_MPI=-DMPI
             DEFAULT : CPP_MPI= -DMPI

FFLAGS_PAR   The options and flags for the F90 compilation of the
             MPI-parallel routines, contained in the Src_seqpar directory 
             (F90 with FREE format).
             Will be used as  $(FC) $(FFLAGS_PAR) -c ...
             For example :
             FFLAGS_PAR=$(FFLAGS) -I/usr/local/mpi/include
             DEFAULT : FFLAGS_PAR=$(FFLAGS) 
              (if no include : MPI-parallel will likely not work !)

LIBS_PAR     The libraries for the MPI-parallel linking.
             Will be used in
             $(FC) $(FLINK) -o abinip abinip.o \
               Src_seqpar/abinip.a ...(other archives) ...  $(LIBS_PAR)
             For example :
             LIBS_PAR=$(LIBS) -lmpi
             DEFAULT : LIBS_PAR=$(LIBS)
              (no MPI library : MPI-parallel will likely not work !)

MACHINE_DEP_F_PAR_SUBS_LIST
MACHINE_DEP_C_PAR_SUBS_LIST
             Lists of machine-dependent Fortran or C routines,
             for the parallel case.
             Presently, no machine need an additional Fortran
             routine, while a C CPU timer must usually be provided
             here (can be etime.c or cclock.c). Note that in the name
             of the routines, .c or .f must be 
             replaced by .par in these lists.
             DEFAULT : null string

COMMAND_PAR  (optional, only needed to make the automatic tests in parallel)
             This command line will be use to run the automatic tests,
             if the fake machine name "paral" is used. Thus, one
             can use it to supercede the usual "../../abinis" command,
             to run the usual sequential code, and replace it by a call
             to abinip. As an example :
             COMMAND_PAR= /usr/local/mpi-pgi/bin/mpirun -np 2 -machinefile dummy.pcpm.ucl.ac.be:2 ../../abinip
             DEFAULT : null string

*******************************************************************

4. NetCDF related contents of makefile_macros

The netcdf package (located in ~abinit/Lib_netcdf/) uses a configure script
to analyze the platform on which netcdf will be compiled.  Some parameters
may not be correctly detected (or not detected at all) by the configure script,
in which case, they should be defined as environment variables before calling 
the netcdf consfigure script.

In order to keep all machine dependent information in a unique file (the makefile_macros
file), a small script has been written which reads the parameters from the makefile_macros,
sets them as environment variables and calls the netcdf configure script.

All netcdf-related parameters should be prefixed by the NC_ prefix (later stripped by the
utility script).  For "working" values for these parameters, see the netcdf web page:

http://www.unidata.ucar.edu/packages/netcdf/INSTALL.html

Here is the list of relevant parameters:

NC_FC		path of FORTRAN compiler.  Usually, set this to your F90 compiler

NC_F90		path of F90 compiler

NC_CPPFLAGS	usually -DNDEBUG, but may also require the type of compiler (e.g.
		pgiFortran,...).  This parameters is required by CFORTRAN program 
		which interfaces C and FORTRAN.  The list of possible values can be found in
		~abinit/Lib_netcdf/src/fortran/cfortran.h 

NC_CC		path of C compiler

NC_CFLAGS	C compiler flags

NC_FFLAGS	Fortran compiler flags

NC_F90FLAGS	F90 compiler flags


*******************************************************************

5. Structure of Makefile, makemake, and tmp_makefile

The makefile_macros file will be used a few times, but always in
the same context : a script called 'makemake' or 'makearch' creates a
'tmp_makefile' from a 'makefile_macros' file and its own data.
The 'makemake' script is used to create the 'tmp_makefile'
in the main directory, while 'makearch' is used to build
the 'tmp_makefile' in all the Lib* and Src* directories.
The 'tmp_makefile' files created in each of these directories
can be used by a make command to compile the source files and 
create either an archive, or the executables.

The chain of actions that lead to the executable abinis when
make abinis
is issued in the ~ABINIT directory is as follows :

1) In Makefile, one finds :

abinis : tmp_makefile_main version perl_in
        make -f tmp_makefile abinis perl

The computer thus looks for the fulfillment of 'tmp_makefile_main', and 'version',
that it finds in Makefile to be :

# Rebuild the tmp_makefile
tmp_makefile_main :
        ./makemake

# Create a one-line version definition
version :
        -rm -f include.version
        echo ' character*6, parameter :: codvsn="$(VERSION)"' > include.version

# Build the internal tests perl scripts
# WARNING : these instructions must stay in this main Makefile,
# as they might be executed without a call to a makefile_macros
perl_in : Test_in/dotest Test_in/Run

Thus, it must execute the makemake in the ~ABINIT directory, then
produce the include.version file, then build the perl scripts, then proceeds with
make -f tmp_makefile abinis perl

We will not examine the making of the perl scripts. Only the generation of the
executable will be the focus of the present documentation.


2) The execution of the makemake script generates a 'tmp_makefile' in the
~ABINIT directory . It contains information from the 'makefile_macros' file,
in addition to definitions common to each machine. We will examine it later.
The include.version file is also generated


3) The command 'make -f tmp_makefile abinis perl' is issued.
We will not describe the 'perl' target.
In tmp_makefile one finds :

# List of dependencies
DEP_ABINIS = $(AR_DRIVE) $(AR_SEQ) $(AR_SUSCEP) \
 $(AR_RESPONSE) $(AR_COMMON) $(AR_IOWFDENPOT) $(AR_WFS)    \
 $(AR_IOVARS) $(AR_RECIPSPACE) $(AR_XC) $(AR_NONLOCAL)     \
 $(AR_FFTS) $(AR_PSP) $(AR_GEOMETRY) $(AR_PARSER)          \
 $(AR_UTIL) $(AR_BASIS) $(AR_NUMRECIP)
abinis: abinis.o $(DEP_ABINIS) $(AR_LIBS)
        echo " abinis will be made " ; echo " "
        cd $(BINDIR) ; \
         $(FC) $(FLINK) -o $@ abinis.o $(DEP_ABINIS) $(LIBS) ; \
         chmod ugo+rx $@
        echo " abinis has been made " ; echo " "

The computer check that abinis.o and the different archives 
(defined at the beginning of the tmp_makefile, for example :
 AR_SEQ = Src_8seqpar/ar_8abinis.a ) have been made previously.
When these conditions are OK, it will
link the objects, thanks to the command $(FC) $(FLINK) ...
We now examine the task 'Src_8seqpar/ar_8abinis.a'. 
The other tasks are rather similar, and even simpler).

In tmp_makefile, one finds :

Src_8seqpar/ar_8abinis.a: $(MACHINE_DEP_LIB_HDR) Src_8seqpar/*.f tmp_makefile_8seqpar
        cd $(BINDIR)/Src_8seqpar; \
         if [ $(MACHINE) != mac ] ; then \
          make -f tmp_makefile ar_8abinis.a VPATH=$(DIR)/Src_8seqpar ; \
         fi ; \
         if [ $(MACHINE) = mac ] ; then \
          make -f tmp_makefile mac_makefile ; \
         fi

The 'tmp_makefile_8seqpar' task is also found in tmp_makefile :


tmp_makefile_8seqpar : Src_0basis/ar_0basis.a
        if [ ! -d $(BINDIR)/Src_8seqpar ] ; then \
         mkdir -p $(BINDIR)/Src_8seqpar ; \
        fi
        cd $(BINDIR) ; \
         if [ ! -f makefile_macros ] ; then \
          cp $(DIR)/makefile_macros . ;    \
         fi
        cd $(BINDIR)/Src_8seqpar ; \
         if [ ! -f object_list ] ; then \
          cp $(DIR)/Src_8seqpar/object_list . ; \
         fi ; \
         if [ ! -f paral_list ] ; then \
          cp $(DIR)/Src_8seqpar/paral_list . ; \
         fi ; \
         $(DIR)/makearch Src_8seqpar ar_8abinis cpp

The archive Src_0basis/ar_0basis.a is a prerequisite
to tmp_makefile_8seqpar, that will be made
in a similar way as Src_8seqpar/ar_8abinis.a

4) The execution of the $(DIR)/makearch script generates a 
'tmp_makefile' in the $(BINDIR)/Src_8seqpar directory, usually ./Src_8seqpar .
It contains the list of subroutines of the code. This list is processed
to give separate list for the sequential version of the code and 
for the parallel version of the code in 'tmp_makefile' .

5) After executing the makearch, the task
tmp_makefile_8seqpar is done. Src_8seqpar/ar_8abinis.a must now take care of the
prerequisite Src_8seqpar/*.f .
Namely, it checks the date of the files to see whether one was changed.
We will not comment on the $(MACHINE_DEP_LIB_HDR) prerequisite,
only needed for Compaq/DEC machines.

6) The 'Src_8seqpar/ar_8abinis.a' task change the working 
directory to $(BINDIR)/Src_8seqpar, then execute

make -f tmp_makefile ar_8abinis.a VPATH=$(DIR)/Src_8seqpar

In the corresponding 'tmp_makefile' of $(BINDIR)/$(SEQPAR), one finds :

ar_8abinis.a : $(OBJS.o)
        $(AR_COMMAND) -rv $@ $?
        (The lines that follows are there only for the generation of statistics.)

The computer checks whether the object files $(OBJS.o) are available,
might compile them, then make the archive, thanks to the quite cryptic command 
$(AR_COMMAND) -rv $@ $?
for which a detailed explanation should be looked for in a manual explaining
the UNIX make tool.

Actually, for further information on the content 
of the tmp_makefile files, one should
resort to such a manual.  One useful reference is "Managing Projects with
make", by Andrew Oran and Steve Talbott, O'Reilly & Associates, Inc., USA, 1991.
This is in the "Nutshell" series of Unix books.

*******************************************************************
