quantum-espresso/README.configure

----------------------------------------------------------------------
HOW TO EDIT THE "configure" SCRIPT
----------------------------------------------------------------------

The "configure" script is generated from its source file
"configure.ac" by the GNU Autoconf utility
(http://www.gnu.org/software/autoconf/).  Don't edit "configure"
directly: whenever it gets regenerated, your changes will be lost.
Instead, edit "configure.ac", then run "autoconf" to regenerate
"configure".  (If you want to keep the old "configure", make a copy
first.)

GNU Autoconf is installed by default on most Unix/Linux systems.  If
you don't have it on your system, you'll have to install it.  Also, if
it bumps an error message saying "configure.in not found", you'll have
to install a more recent version.  Version 2.53 at least is known to
work.

"configure.ac" is a regular Bourne shell script (i.e., "sh" -- not
csh!), except that:
- capitalized names starting with "AC_" are Autoconf macros.  Normally
  you shouldn't have to touch them.
- square brackets are normally removed by the macro processor.  If you
  need a square bracket (that should be very rare), you'll have to
  write two.
You may refer to the GNU Autoconf Manual for more info.

"make.sys.in" is the source file for "make.sys", that "configure"
generates: you might want to edit that file as well.  The generation
procedure is as follows: if "configure.ac" contains the macro
"AC_SUBST(name)", then every occurrence of "@name@" in the source
file will be substituted with the value of the shell variable "name"
at the point where AC_SUBST was called.

Similarly, "configure.msg" is generated from "configure.msg.in": this
file is only used by "configure" to print its final report, and isn't
needed for the compilation.  We did it this way so that our
"configure" may also be used by other projects, just by replacing the
Quantum-ESPRESSO-specific "configure.msg.in" by your own.

"configure" writes a detailed log of its operation to "config.log".
When any configuration step fails, you may look there for the relevant
error messages.  Note that it is normal for some checks to fail.

----------------------------------------------------------------------
HOW TO ADD SUPPORT FOR A NEW ARCHITECTURE

In order to support a previously unsupported architecture, first you
have to figure out which compilers, compilation flags, libraries
etc. should be used on that architecture.
In other words, you have to write a "make.sys" that works: you may use
the manual configuration procedure for that (see the Quantum-ESPRESSO
User's Guide).  Then, you have to modify "configure" so that it can
generate that "make.sys" automatically.

To do that, you have to add the case for your architecture in several
places throughout "configure.ac":

*** 1: Detect architecture. ***

Look for these lines:

  if test "$arch" = ""
  then
          case $host in
                  ia64-*-linux-gnu )      arch=ia64   ;;
                  x86_64-*-linux-gnu )    arch=and64  ;;
                  *-pc-linux-gnu )        arch=ia32   ;;
                  etc.

Here you must add an entry corresponding to your architecture and
operating system.  Run "config.guess" to obtain the string identifying
your system.
For instance on a PC it may be "i686-pc-linux-gnu", while on IBM SP4
"powerpc-ibm-aix5.1.0.0".  It is convenient to put some asterisks to
account for small variations of the string for different machines of
the same family.  For instance, it could be "aix4.3" instead of
"aix5.1", or "athlon" instead of "i686"...

*** 2: Select compilers. ***

Look for these lines:

  # candidate compilers, archiver and flags based on architecture
  case $arch in
  ia64 | amd64 )
        ...
  ia32 )
        ...
  aix )
        ...
  etc.

Add an entry for your value of $arch, and set there the appropriate
values for several variables:

- "try_f90" should contain the list of candidate Fortran 90 compilers,
  in order of decreasing preference (i.e. configure will use the first
  it finds).  If your system has parallel compilers, you should list
  them in "try_mpif90".

- "try_ar", "try_arflags": for these, the values "ar" and "ruv" should
  be always fine, unless some special flag is required (e.g., -X64
  with sp4).  You should also set "ranlib=ranlib" if needed;
  otherwise, the default of "ranlib=echo" will be used (i.e., don't
  use ranlib).

- you should define "try_dflags" if the Quantum-ESPRESSO codes contain any
  "#ifdef" specific to your machine: for instance "try_dflags=-D__AIX"
  (on IBM machines) or "try_dflags=-D__LINUX" (on 32-bit PCs with
  Linux) or "try_dflags=-D__LINUX64" (Linux on Itanium and Opteron).

For example, here's the entry for Mac OS X:

  mac )
          try_mpif90="mpxlf90 mpf90"
          try_f90="xlf90 f90"
          try_ar="ar"
          try_arflags="ruv"
          try_dflags="-D__MAC -D__XLF"
          ranlib="ranlib"
          ;;

Then look for these lines:

  # check parallel Fortran 90 compiler
  ...
  AC_PROG_F77($mpif90)
  mpif90=$F77

  case "$arch" in
  ia32 | ia64 | amd64 )
        ...

and just below:

  case "$arch:$mpif90" in
  *:mpif90 )
        ....
  etc.

If you don't have parallel Fortran and C compilers, you can skip this
step.  Otherwise, in either of these two case blocks you have to add
an entry for your architecture *and* parallel Fortran 90 compiler
(Linux case is treated specially because there is a huge variety of
compilers for that OS).  There you have to set:

- "try_mpicc", "try_mpif77": list of C and Fortran 77 compilers, also
  in decreasing order of preference.  This is done at this later stage
  because the choice depends on the Fortran 90 compiler.  For
  instance, if $mpif90=ifort you'll want to use icc, while if
  $mpif90=pgf90 you'll want pgcc.

A few compilers require some extra work here: for instance, if the
Intel Fortran compiler was selected, you need to know the version
because different versions need different flags.

For example, here are the entries for parallel XL compilers on AIX:

  aix:mpxlf*_r )
          try_mpicc="mpcc_r"
          try_mpif77="mpxlf_r"
          ;;

Then look for these lines:

  # check serial Fortran 90 compiler
  ...
  AC_PROG_F77($f90)
  f90=$F77
  ...
  case "$arch:$f90" in
  *:ifort* )
        ...

Here you have to add an entry for your architecture and serial C and
Fortran 77 compilers (just like the previous case, but serial
compilers here).

Finally, at this point:

  # check whether the C and Fortran compilers are compatible
  case "$arch:$cc:$f90" in
  	# list supported combinations here
  ...

you may insert the case corresponding to your architecture, with the
compilers that are known to work.  Otherwise "configure" will issue a
warning about "unsupported C/Fortran compilers combination", which you
may however ignore.

*** 3: Specify compilation flags. ***

Look for these lines:

  # check Fortran compiler flags
  ...
  case "$arch:$f90" in
  ia64:ifort* | amd64:ifort* )
        ...
  ia64:ifc* )
  	...
  etc.

Add an entry for your case and define:

- "try_fflags": flags for Fortran 77 compiler.

- "try_f90flags": flags for Fortran 90 compiler.
  In most cases they will be the same as in Fortran 77 plus some
  others.  In that case, define them as "\$(FFLAGS) -something_else".

- "try_fflags_noopt": flags for Fortran 77 with all optimizations
  turned off: this is usually "-O0".
  These flags must be used for compiling flib/dlamch.f (part of our
  version of Lapack): it won't compile properly with optimizations.

- "try_f90flags_noopt" : as above, but for Fortran 90

- "try_ldflags": flags for the linking phase (not including the list
  of libraries, that is compiled later).  Note that $mpif90 will be
  used as the linker for Quantum-ESPRESSO programs.

- "try_ldflags_static": additional flags to select static compilation
  (i.e., don't use shared libraries).

- "try_dflags": must be defined if there is in the code any #ifdef
  specific to your compiler (for instance, -D__INTEL for Intel
  compilers).  Define it as "$try_dflags -D..." so that pre-existing
  flags, if any, are preserved.

- if the Fortran 90 compiler is able to invoke the C preprocessor
  automatically before compiling, define "have_cpp=1"; otherwise,
  leave it undefined (or define it as 0).
  The appropriate compilation rules will be generated accordingly.
  If the compiler requires that any flags be specified in order to
  invoke the preprocessor (for example, "-fpp " -- note the space),
  specify them in "pre_fdflags".

For example, here's the entry for ifort on Linux PC:

  ia32:ifort* )
          try_fflags="-O2 -tpp6 -assume byterecl"
          try_f90flags="\$(FFLAGS) -nomodule"
          try_fflags_noopt="-O0 -assume byterecl"
          try_f90flags_noopt="\$(FFLAGS_NOOPT) -nomodule"
          try_ldflags=""
          try_ldflags_static="-static"
          try_dflags="$try_dflags -D__INTEL"
          pre_fdflags="-fpp "
          have_cpp=1
          ;;

Then, look for these lines:

  case "$arch:$cc" in
  *:icc )
  	...
  *:pgcc )
  	...
  etc.

Add an entry for your case and define:

- "try_cflags": flags for C compiler.

- "c_ldflags": flags for linking, when using the C compiler as linker.
  This is needed to check for libraries written in C, such as FFTW.

- if you need a different preprocessor from the standard one ($CC -E),
  define it in "try_cpp".

For example for XLC on AIX:

  aix:mpcc* | aix:xlc* | aix:cc )
          try_cflags="-q64 -O2"
          c_ldflags="-q64"
          ;;

Finally, if you have to use a nonstandard preprocessor, look for these
lines:

  # preprocessor
  AC_PROG_CPP
  ...
  echo $ECHO_N "setting CPPFLAGS... $ECHO_C"
  case $cpp in
  	cpp) try_cppflags="-P -traditional" ;;
  	fpp) try_cppflags="-P"              ;;
  	...

and set "try_cppflags" as appropriate.

*** 4. Search for libraries. ***

To instruct "configure" to search for libraries, you must tell it two
things: the names of libraries it should search for, and where it
should search.

The following libraries are searched for:

- BLAS or equivalent
  Some vendor replacements for BLAS that are supported by
  Quantum-ESPRESSO are:
    MKL on Linux
    ACML on Linux amd64
    essl on AIX
    complib.sgimath on sgi origin
    SCSL on sgi altix
    scilib on Cray T3E
    SUNperf on sparc
    cxml on alpha
  Moreover, ATLAS is used over BLAS if available.

- LAPACK or equivalent
  Some vendor replacements for LAPACK that are supported by
  Quantum-ESPRESSO are:
    mkl on linux
    SUNperf on sparc

- FFTW (version 2.x) or another supported FFT library
  The latter include:
    essl on aix
    SUNperf on sparc

- the MASS vector math library on aix

- an MPI library
  This is often automatically linked by the compiler

If you have another replacement for the above libraries, you'll have
to insert a new entry in the appropriate place.

This is unfortunately a little bit too complex to explain.
Basic info: "AC_SEARCH_LIBS(function, name, ...)" looks for symbol
"function" in library "libname".  If that is found, "-lname" is
appended to the LIBS environment variable (initially empty).
The real thing is more complicated than just that because the
"-Ldirectory" option must be added to search in a nonstandard
directory, and because a given library may require other libraries as
prerequisites (for example, Lapack requires BLAS).  Hope this helps.