The build system of ABINIT 5.

5 A denitive guide
Yann Pouillon Draft version - December 2, 2007

Contents
I Users
1 Overview of the build system 1.1 Main objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2 Underlying concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 The congure script 2.1 Running congure . . . . . . 2.2 Compiler options . . . . . . . 2.3 MPI options . . . . . . . . . . 2.4 External libraries . . . . . . . 2.5 Other options . . . . . . . . . 2.6 Options provided by Autoconf 2.7 Environment variables . . . . 2.8 The conguration process . . .

1
3 3 3 5 5 6 7 9 10 10 13 14

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

II Developers
3 Preprocessing macros 3.1 Propagating information to the source code 3.2 Naming conventions . . . . . . . . . . . . 3.3 If statements . . . . . . . . . . . . . . . . . 3.4 Preprocessing macros of ABINIT 5 . . . . 3.4.1 Generic macros . . . . . . . . . . . 3.4.2 Architecture-related macros . . . . 3.4.3 Optional library macros . . . . . . 3.4.4 MPI macros . . . . . . . . . . . . . 3.4.5 Compiler macros . . . . . . . . . . 3.4.6 Fortran-specic macros . . . . . . . 3.4.7 Renamed macros . . . . . . . . . . 3.4.8 Unmaintained macros . . . . . . . 3.4.9 Removed macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

17
19 19 19 20 20 20 20 21 21 22 22 23 23 23

ii 4

Contents Adding external libraries / plug-ins 4.1 Overall procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.2 The library makele . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.3 Fine-tuning abinit.amf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 25 26 27

III Maintainers
5 Extending the build system 5.1 Prerequisites . . . . . . 5.2 Adding scripts . . . . . 5.3 Adding M4 macros . . 5.4 Editing congure.ac . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

29
31 31 32 32 32

ii

Part I Users

Chapter 1 Overview of the build system

1.1 Main objectives

The build system of ABINIT is here to fulll the following objectives: take care of the makeles;

1.2

Underlying concepts

Build directory support Cong-le support

Chapter 2 The congure script

2.1 Running congure

Autoconf is a tool producing a shell script that automatically congures software source code to adapt to many kinds of environments. The conguration script produced by Autoconf is independent of Autoconf when it is run, so that its users do not need to install Autoconf. In other words: you do not need have Autoconf installed to build ABINIT. Moreover this conguration script requires no manual user intervention when run; it do not normally even need an argument specifying the system type. Instead, it individually tests for the presence of each feature that the software package it is tuned to might need. However it does not yet have paranormal powers, and in particular has no access to what you have in mind. You still have to explicitely interact with it for now, and the best way to do it is through the numerous options of this congure script. The congure script accepts two classes of parameters: script-provided options, composed of triggers (enable/disable) and speciers (with/without), plus a few special options; environment variables, which inuence the overall behaviour of the script. A typical call looks like: ./configure [OPTION] ... [VAR=VALUE] ... Here is what [OPTION] stands for: Type ... if you want to ... --enable-FEATURE[=ARG] activate FEATURE [ARG=yes] --disable-FEATURE do not activate FEATURE (same as --enable-FEATURE=no) --with-PACKAGE[=ARG] use PACKAGE [ARG=yes] --without-PACKAGE do not use PACKAGE (same as --with-PACKAGE=no) 5

Chapter 2. The congure script

To assign environment variables (e.g., CPP, FC, . . . ), you specify them as VAR=VALUE couples on the command line. Please note that there must be no spaces around the = sign. Moreover, VALUE must be quoted when it contains spaces. If some assignements are ignored by the congure script, just try the other way around: VAR=VALUE ... ./configure [OPTION] ... If you run congure from a build directory, which we highly recommend, you will of course type ../configure instead of ./configure. In this chapter, the defaults for the options are specied in square brackets. No brackets means that there is no default value.

2.2

Compiler options

ABINIT provides an comprehensive database of optimization ags. They will suit your needs in most cases. You may however tune them using the options listed on table 2.1. When set, they replace the ags that would automatically be fetched from the database otherwise. Linking additional libraries should be done through the use of the CC LIBS (C programs), CXX LIBS (C++ programs) and FC LIBS (Fortran programs) environment variables. When specied, they replace the settings provided by the build system during the optimization process. FC LIBS is currently the only variable producing visible effects, but this will change in the future. More details may be found in the Environment variables section below. The build system provides 3 different possible optimization levels, controlled by the --enable-optlevel option: safe; standard; aggressive. Their names are self-explanatory, and the default is of course standard, which corresponds to the optimization database present in the previous versions of ABINIT. It is obvious that the aggressive level should be used with extreme care. There are 3 levels of debugging as well, available through --enable-debug: no: do not produce debugging information (default); yes: produce debugging information if the compilers support it and turn-off optimizations; symbols: produce debugging information whenever possible, while keeping optimizations. Please note that the support for 64-bit architectures is still incomplete and will be reworked during the next development cycle of ABINIT. 6

2.3. MPI options Option --enable-64-bit-flags --enable-debug --enable-optlevel --enable-tricks --with-cppflags=FLAGS --with-cc-optflags=FLAGS --with-cc-ld-optflags=FLAGS --with-cc-ld-optlibs=LIBS --with-cxx-optflags=FLAGS --with-cxx-ld-optflags=FLAGS --with-cxx-ld-optlibs=LIBS --enable-fc-wrapper --with-fc-optflags=FLAGS --with-fc-ld-optflags=FLAGS --with-fc-ld-optlibs=LIBS

7 Description Use 64-bit ags with all compilers Activate debug mode (no optimizations) [default=no] Set optimization level [default=standard] Enable compiler tips and tricks (recommended) [default=yes] Set preprocessing options Set optimizations of C routines Prepend ags when calling the C linker Append libraries when calling the C linker Set optimizations of C++ routines Prepend ags when calling the C++ linker Append libraries when calling the C++ linker Wrap Fortran compiler calls [default=guessed] Set-up optimization of Fortran routines Prepend ags when calling the Fortran linker Append libraries when calling the Fortran linker

Table 2.1: ABINIT compiler options.

2.3

MPI options

In addition to serial optimization, ABINIT provides parallel binaries relying upon the MPI library. If you do not know what MPI stands for, then you really need the help of a computer scientist before reading this section. First let us make clear that we cannot provide you with any support to install MPI. If you need to do it, we advise you to ask help to your system and/or network administrators, because it will likely require special permissions and fair technical skills. In many cases you will already have a working installation of MPI at your disposal, and will at most need some information about its location. Providing extended support for MPI is extremely delicate: there is no standard location for the package, there are concurrent implementations following different philosophies, and Fortran support is compiler-dependent. Moreover, there might be several versions of MPI installed on your system, and you have to choose one of them carefully. In particular, if you want to enable the build of parallel code in ABINIT which you will likely do you have to build ABINIT with the same Fortran compiler that has been used for MPI. This is why the congure script will tell you that it selected other compilers than those you specied if it needs to preserve self-consistency between the sequential and parallel versions of the code. Up to ABINIT 5.3, the interface to MPI support in the build system was a little bit confusing, and was permanently undergoing a lot of changes. The users needs have rst been claried in the lifespan of ABINIT 5.4, and the implementation has been heavily xed between ABINIT 5.5.1 and 5.5.2, leading to some more adjustments. The user interface has now reached a sufcient level of consistency to be frozen. The MPI options provided by the 7

8 Option --enable-mpi --enable-mpi-fft --enable-mpi-io --enable-mpi-trace --with-mpi-prefix=PATH --with-mpi-cppflags=FLAGS --with-mpi-cflags=FLAGS --with-mpi-cc-ldflags=FLAGS --with-mpi-cc-libs=LIBS --with-mpi-cxxflags=FLAGS --with-mpi-cxx-ldflags=FLAGS --with-mpi-cxx-libs=LIBS --with-mpi-fcflags=FLAGS --with-mpi-fc-ldflags=FLAGS --with-mpi-fc-libs=LIBS --with-mpi-runner=PROG

Chapter 2. The congure script Description Enable MPI support [default=guessed] Enable band/FFT parallelism [default=no] Enable parallel I/O [default=no] Enable MPI time tracing [default=no] Prex for the MPI installation MPI preprocessing ags for parallel code MPI compile ags for C parallel code MPI link ags to prepend for parallel C programs MPI libraries to append for parallel C programs MPI compile ags for C++ parallel code MPI link ags to prepend for parallel C++ programs MPI libraries to append for parallel C++ programs MPI compile ags for Fortran parallel code MPI link ags to prepend for parallel Fortran programs MPI libraries to append for parallel Fortran programs Full path to the MPI runner program

Table 2.2: MPI options of ABINIT. build system are summarized in table 2.2. They are valid from the 5.5.2 version of ABINIT on. The --enable-mpi and --with-mpi-prex options to the congure script are controlling all the others: --enable-mpi=no switches off the build of parallel code and is the default, because miscongured MPI installations may crash the congure script (see the Environment variables section for a discussion about this); --enable-mpi=yes triggers MPI auto-detection, leaving a lot of decisional freedom to the build system; --enable-mpi=manual bypasses auto-detection and takes user-specied build parameters as-is; the parallel code will be built independently of the relevance and correctness of these parameters. If --enable-mpi is set to yes, the parallel code will be built only if a usable MPI implementation can be detected. If the --with-mpi-prex option is provided, enable mpi is automatically set to yes and the build system tries to nd a usable generic MPI installation at the specied location very early during the conguration. If this step is successful, the compilers and the runner provided by MPI are used in lieu of the user-specied ones, and no further test is performed. If --with-mpi-prex is not present, the build of parallel code will be deactivated unless --enable-mpi is explicitely set to yes. If the rst attempt fails, a second one is undertaken once the compilers have been congured. The build system then checks whether the compilers are able to build MPI source 8

2.4. External libraries Library bigdft etsf-io etsf-xc fftw fox linalg netcdf wannier90 xmlf90 Internal Required Depends Note yes no yes no netcdf yes no Needs more testing no no yes no Currently unsupported yes yes yes no yes no Test library for the plug-in feature yes no Soon replaced by FoX Table 2.3: Specications of the ABINIT libraries.

code natively, taking advantage of the user-specied parameters. If successful, a MPI runner will be looked for using the PATH environment variable. If something goes wrong, the build of parallel code will be automatically disabled. In such a case, and as a last resort, the user may force the build through the use of --enable-mpi=manual. Additional levels of parallelization may be activated, though they are still experimental and meant to be used by developers only: --enable-mpi-fft: parallel FFT; this feature will be soon fully integrated and replaced by an input variable; --enable-mpi-io: parallel le I/O; --enable-mpi-trace: parallel time tracing. You will nd a detailed description of all these options in the source package of ABINIT, within the MPI support section of the abinit/doc/cong/build-cong.ac template. We warmly recommend you to have a close look at this le and to use it as much as you will.

2.4

External libraries

The congure script of ABINIT provides a unied way of dealing with external libraries, by means of a trigger (enable/disable) and two speciers (for include and link ags) for each package. Below the surface, things are however much more complex: some libraries are required by ABINIT, others not; some are contained within the source package, others are too big to be included; a few of them depend on other external libraries, which may or may not be found within the package. The current situation is summarized in table 2.3, and the corresponding options are described in table 2.4. When a library is required and cannot be found outside the source package, the build system systematically restores consistency by ignoring user requests and disabling the corresponding

10 support.

Chapter 2. The congure script

Providing automatic external library detection lead to complicate the build system too much, and jeopardized its maintainability. Hence we decided to aim at maximum simplicity. This means that you need to provide the include and link ags yourself, just as you would do when directly calling the compiler, e.g.:
./configure \ --enable-netcdf \ --with-netcdf-includes="-I/opt/etsf/include/g95" \ --with-netcdf-libs="-L/opt/etsf/lib -lnetcdf"

2.5

Other options

The congure script provides a few more options. Though most of them will only be used in specic situations, they might prove very convenient in these cases. The full list of special options may be found in table 2.5. The build system of ABINIT makes it possible to use cong les to store your preferred build parameters. A fully documented template is provided in the source code under abinit/doc/cong/build-cong.ac, along with a few examples in abinit/doc/cong/build-examples/. After editing this le to suit your needs, you may save it as $HOME/.abinit/build/<hostname>.ac to keep these parameters as per-user defaults. Just replace <hostname> by the name of your machine, excluding the domain name. E.g.: if your machine is called myhost.mydomain, you will save this le as $HOME/.abinit/build/myhost.ac. You may put this le at the top level of an ABINIT source tree as well, in which case its denitions will apply to this particular tree only. Using cong les is highly recommended, since it saves you from typing all the options on the command-line each time you build a new version of ABINIT.

2.6

Options provided by Autoconf

Every congure script generated by Autoconf provides a basic set of options, whatever the package and the environment. They either give information on the tunable parameters of the package or inuence globally the build process. In most cases you will only need a few of them, if any. Overall conguration:

10

2.6. Options provided by Autoconf

11

Option --enable-bigdft --with-bigdft-includes --with-bigdft-libs --enable-etsf-io --with-etsf-io-includes --with-etsf-io-libs --enable-etsf-xc --with-etsf-xc-includes --with-etsf-xc-libs --enable-fftw --enable-fftw-threads --with-fftw-libs --enable-fox --with-fox-includes --with-fox-libs --with-linalg-libs --enable-netcdf --with-netcdf-includes --with-netcdf-libs --enable-wannier90 --with-wannier90-includes --with-wannier90-libs --enable-xmlf90 --with-xmlf90-includes --with-xmlf90-libs

Description Enable support for the BigDFT wavelet library [default=no] Include ags for the BigDFT library Library ags for the BigDFT library Enable support for the ETSF I/O library [default=no] Include ags for the ETSF I/O library Library ags for the ETSF I/O library Enable support for the ETSF exchange-correlation library [default=no] Include ags for the XC library Library ags for the ETSF XC library Enable support for the FFTW library [default=no] Enable support for the threaded FFTW library [default=no] Library ags for the FFTW library Enable support for the FoX I/O library [default=no] Include ags for the FoX I/O library Library ags for the FoX I/O library Library ags for the linalg library Enable support for the NetCDF I/O library [default=no] Include ags for the NetCDF library Library ags for the NetCDF library Enable support for the Wannier90 library [default=no] Include ags for the Wannier90 library Library ags for the Wannier90 library Enable support for the XML Fortran 90 I/O library [default=no] Include ags for the XMLF90 library Library ags for the XMLF90 library

Table 2.4: External library options of ABINIT.

Option --enable-config-file --with-config-file=FILE --enable-cclock --enable-stdin

Description Read options from cong les [default=yes] Specify cong le to read options from Use C clock for timings [default=no] Read le lists from standard input [default=yes]

Table 2.5: Special options of ABINIT.

11

12 Option -h, --help --help=short --help=recursive -V, --version -q, --quiet, --silent --cache-le=FILE -C, --cong-cache -n, --no-create --srcdir=DIR Installation directories: Option --prefix=PREFIX --exec-prefix=EPREFIX

Chapter 2. The congure script Description display all options and exit display options specic to the ABINIT package display the short help of all the included packages display version information and exit do not print checking... messages cache test results in FILE [disabled] alias for --cache-le=cong.cache do not create output les nd the sources in DIR [congure dir or ..]

Description install architecture-independent les in PREFIX [/opt] install architecture-dependent les in EPREFIX [PREFIX]

By default, make install will install all the les in subdirectories of /opt/abinit/<version>. You can specify an installation prex other than /opt using --prefix, for instance --prefix=$HOME. For a ner-grained control, use the options below. Fine tuning of the installation directories: Option --bindir=DIR --sbindir=DIR --libexecdir=DIR --datadir=DIR --sysconfdir=DIR --sharedstatedir=DIR --localstatedir=DIR --libdir=DIR --includedir=DIR --oldincludedir=DIR --infodir=DIR --mandir=DIR Program names: Description user executables [EPREFIX/bin] system admin executables [EPREFIX/sbin] program executables [EPREFIX/libexec] read-only architecture-independent data [PREFIX/share] read-only single-machine data [PREFIX/etc] modiable architecture-independent data [PREFIX/com] modiable single-machine data [PREFIX/var] object code libraries [EPREFIX/lib] C header les [PREFIX/include] C header les for non-gcc [/usr/include] info documentation [PREFIX/info] man documentation [PREFIX/man]

12

2.7. Environment variables Option --program-prefix=PREFIX

13

Description prepend PREFIX to installed program names --program-suffix=SUFFIX append SUFFIX to installed program names --program-transform-name=PROGRAM run sed PROGRAM on installed program names System types: Option --build=BUILD --host=HOST --target=TARGET Developer options: Option --enable-shared[=PKGS] --enable-dependency-tracking --enable-dependency-tracking --with-gnu-ld Description build shared libraries [default=no] speeds up one-time build do not reject slow dependency extractors assume the C compiler uses GNU ld [default=no] Description congure for building on BUILD [guessed] cross-compile to build programs to run on HOST [BUILD] congure for building compilers for TARGET [HOST]

2.7

Environment variables

In table 2.6, you will nd short descriptions of the most useful variables recognized by the congure script of ABINIT. Use these variables to override the choices made by configure or to help it to nd libraries and programs with nonstandard names/locations. Please note that they always have precedence over command-line options. There are 2 environment variables of critical importance to the build system, though they cannot be managed by congure: PATH, which denes the order in which the compilers will be found, and the number of hits; LD LIBRARY PATH, which will greatly help the build system nd usable external libraries, in particular MPI. Improper settings of these 2 variables may cause a great confusion to the congure script in some cases, in particular when looking for MPI compilers and libraries. A typical issue encountered is the following crash:
checking for gcc... /home/pouillon/hpc/openmpi-1.2.4-gcc4.1/bin/mpicc checking for C compiler default output file name... a.out checking whether the C compiler works... configure: error: cannot run C compiled programs. If you meant to cross compile, use --host. See config.log for more details.

13

14 Option AR ARFLAGS CPP CPPFLAGS

Chapter 2. The congure script

Description Archiver Archiver ags C preprocessor C/C++ preprocessor ags, e.g. -I<include dir> if you have headers in a non-standard directory named <include dir> CC C compiler command CFLAGS C compiler ags CC LDFLAGS C link ags to prepend to the command line CC LIBS Libraries to append when linking a C program CXX C++ compiler command CXXFLAGS C++ compiler ags CXX LDFLAGS C++ link ags to prepend to the command line CXX LIBS Libraries to append when linking a C++ program FC Fortran compiler command FCFLAGS Fortran compiler ags FC LDFLAGS Fortran link ags to prepend to the command line FC LIBS Libraries to append when linking a Fortran program Table 2.6: Inuencial environment variables for the build system of ABINIT. And a look at cong.log shows:
... configure:6613: checking whether the C compiler works configure:6623: ./a.out ./a.out: error while loading shared libraries: libmpi.so.0: cannot open shared object file: No such file or directory configure:6626: $? = 127 configure:6635: error: cannot run C compiled programs. ...

This kind of error results from a missing path in the LD LIBRARY PATH environment variable, and can be solved very easily, in the present case this way:
export LD_LIBRARY_PATH="/home/pouillon/hpc/openmpi-1.2.4-gcc4.1/lib:${LD_LIBRARY_PATH}"

in the case of a BASH shell, and by:

setenv LD_LIBRARY_PATH "/home/pouillon/hpc/openmpi-1.2.4-gcc4.1/lib:${LD_LIBRARY_PATH}"

for a C shell.

2.8

The conguration process

Conguring ABINIT is a delicate step-by-step process, because each component is interacting permanently with most others. This is reected in the output of congure, that we describe in 14

2.8. The conguration process this section.

15

The process starts with an overall startup, where the basic parameters required by Autoconf and Automake are set. During the second part of this step, the build system of ABINIT reads the options from the command line and from a cong le, making sure that the environment variables will always have precedence over the command-line options, which in turn override the options read from the cong le. It then reports about changes in the user interface of the build system, warning the user if they have used an obsolete option. The next step is about ensuring the overall consistency of the options provided to congure. The build system takes the necessary decisions so that the code may be built safely. It then parses the options, and issues an error if the user has provided invalid options. The error messages give all the information needed to x the problems. Then comes the MPI startup stage, which the rst half of the conguration of MPI support. This must happen before any Autoconf compiler test, in order to give the build system the possibility to consistently select the MPI compilers that have been detected. This step is mandatory to avoid conguration issues later on, due to mismatches between the sequential and parallel compilers. The next step is to nd the various utilities that the build system may need along the rest of the conguration process. This runs usually very smoothly, since these tools are found on most of the platforms ABINIT runs on. The preprocessing step is where serious things really start. The C preprocessor is searched for, which involves in turn the search for a working C compiler. At this point, all compilers must already have been selected. This is also typically where congure may crash if the MPI installation detected is broken or miscongured (see Environment variables section within this chapter), because the C compiler will not be able to produce executables. This is why MPI support is disabled by default, and we are open to any suggestion. The three next steps involve the search for suitable C, C++ and Fortran compilers, the detection of their type, and the application of tricks to have them work properly on the users platform. These are also stages where the conguration may fail, in particular if no suitable Fortran compiler is found. Then the build system congures the use of the archiver, to build the numerous libraries that are part of ABINIT. The two next steps are about ne-tuning the compile ags so that the build will work ne if the architecture is 64-bit (work still in progress), and to set the adequate level of optimization according to the platform parameters identied so far. Here comes the probably most critical step of the conguration: MPI support. If everything could be set during the MPI startup stage, no further test is performed, and the parallel code is 15

16

Chapter 2. The congure script

marked for building. If not, the build system will try to detect whether the compilers are able to build MPI source code and set the MPI options accordingly. Once all this is done, the build system can set the parameters for the linear algebra and FFT libraries (work still in progress), before turning to the plug-ins. One last conguration step is dedicated to the nightly build support, which is now working but still at an early stage of development. The very last step is to output the conguration to the numerous makeles, as well as to a few other important les. At the end, a warning is issued if the Fortran compiler in use is known to cause trouble.

16

Part II Developers

17

Chapter 3 Preprocessing macros

3.1 Propagating information to the source code

While many arguments of the congure script control the way ABINIT is built, some of them --- in addition to the results of the tests performed at congure-time --- greatly inuence what will be built. In the latter case, the information has to be propagated up to the source code, which is done by means of preprocessing macros. They are created by the AC DEFINE macro of Autoconf, or specied by the user on the command line. Macros are (name,value) pairs allowing the mapping of a sequence to another. Names are usually single words, while values usually range from simple numbers to very complex sequences of instructions. During compilation, name is replaced by value every time it is encountered, this process being called macro expansion. Special lines, starting with the # character in C, allow for more operations on macros, like setting, unsetting or tests. Last but not least, the concept of macro is not limited to any programming language, and macros are indeed ubiquitous in the programming world. The build of ABINIT leads to the creation of many preprocessing macros (73 in ABINIT 5.5), which are stored in cong.h. Besides command-line options, this le is the only link between the build system and the source code of ABINIT, and this is the reason why all of them must include it at their very beginning.

3.2

Naming conventions

As far as preprocessing directive names are concerned, ABINIT abides strictly by the GNU Coding Standards. This means in particular that: all user-dened compiler directives must be upper case; all names must start with a letter; names may contain capital letters, digits and underscores only;

19

20

Chapter 3. Preprocessing macros

Directives related to features that may or may not be present depending on the conguration must begin by the keyword HAVE *, e.g. HAVE CONFIG H, HAVE NETCDF, HAVE ETSF XC, etc.

3.3

If statements

If statements should all begin with #if. We kindly ask you not to use #ifdef, but #if defined instead. A line ending an if statement must contain the #endif keyword only. The same holds for #else. Here is a typical example:
#if defined HAVE_CONFIG_H #include "config.h" #endif

We thank you in advance for following these simple rules, as it will greatly simplify the automatic checks and xes of the source code.

3.4

Preprocessing macros of ABINIT 5

ABINITGW CONTRACT HAVE CONFIG H Light version of ABINIT, for GW calculations Design-by-contract code Mandatory: use cong.h if present

3.4.1 Generic macros

3.4.2 Architecture-related macros

OS IRIX OS LINUX OS MACOSX OS WINDOWS VMS IRIX operating system Linux operating system Mac OS X operating system DOS/Windows operating system VAX/VMS architecture

20

3.4. Preprocessing macros of ABINIT 5

21

3.4.3 Optional library macros

HAVE HAVE HAVE HAVE HAVE HAVE HAVE HAVE HAVE HAVE HAVE HAVE HAVE HAVE COMPAQ FFT FFTW FFTWTHREADS HP MLIB SCALAPACK SGI MATH IBM ESSL IBM ESSL OLD NEC ASL NETCDF BIGDFT ETSF IO ETSF XC XMLF90 HP/Compaq/DEC FFT library FFTW library FFTW library (threaded version) HP mathematical library SCALAPACK linear algebra library SGI mathematical library IBM mathematical library IBM mathematical library (old version) NEC mathematical library NetCDF le I/O library BigDFT wavelet library ETSF le I/O library ETSF exchange-correlation library XML Fortran I/O library

3.4.4 MPI macros

MPI macros may not be included in the cong.h le, as it would preclude the build of sequential code. They should be specied within the compiler command line. The following table gives the full list of permitted MPI macros and the way they are managed. Manual handling is done through the --with-mpi-cppags option of congure. Option Description MPI MPI statements follow MPI1 MPI version 1 MPI2 MPI version 2 MPI3 MPI version 3 MPI EXT MPI HTOR routines (?) MPI FFT Parallel FFT MPI IO Parallel I/O MPI TRACE Timing within parallel routines Management Build system Manual Manual Manual Manual Build system Build system Build system

21

22

Chapter 3. Preprocessing macros

3.4.5 Compiler macros

FC FC FC FC FC FC FC FC FC FC FC FC FC FC ABSOFT COMPAQ FUJITSU GNU G95 HITACHI HP IBM INTEL MIPSPRO NAG NEC PGI SUN ABSoft Fortran compiler HP/Compaq/DEC Fortran compiler Fujitsu Fortran compiler GNU Fortran compiler (gfortran) G95 Fortran compiler (g95) Hitachi Fortran compiler HP Fortran compiler IBM XL Fortran compiler Intel Fortran compiler SGI MipsPro Fortran compiler NAGWare Fortran compiler NEC Fortran compiler PGI Fortran compiler Sun Fortran compiler

The same holds for C and C++ compilers.

3.4.6 Fortran-specic macros

HAVE FORTRAN EXIT The Fortran compiler accepts exit() USE CCLOCK Use C clock for timings

22

3.4. Preprocessing macros of ABINIT 5

23

3.4.7 Renamed macros

Option IFC ibm NAGf95 mpi MPIEXT TRACE FFTW FFTWTHREADS bim bmi cen dec alpha hp hpux nec nolib sgi sr8k vpp VMS P6 macosx CHGSTDIO Replaced by FC INTEL FC IBM FC NAG MPI MPI EXT MPI TRACE HAVE FFTW HAVE FFTWTHREADS HAVE IBM ESSL HAVE IBM ESSL HAVE NEC ASL, FC NEC FC COMPAQ HAVE HP MLIB, FC HP HAVE HP MLIB HAVE NEC ASL, FC NEC HAVE COMPAQ FFT HAVE SGI MATH, FC MIPSPRO FC HITACHI FC FUJITSU VMS i386 OS MACOSX READ FROM FILE Version 5.1 5.1 5.1 5.1 5.1 5.1 5.1 5.1 5.1 5.1 5.1 5.1 5.1 5.1 5.1 5.1 5.1 5.1 5.1 5.1 5.1 5.1 5.1

3.4.8 Unmaintained macros

OPENMP OpenMP parallelism T3E Cray T3E architecture TEST AIM Optional checks for AIM

3.4.9 Removed macros

The following preprocessing macros have been removed from the ABINIT source code.

23

24 Option OLD INIT

Chapter 3. Preprocessing macros Last version Comments 4.6 Was used in src/04wfs/wfconv.F90 to initialize the wavefunctions, and has been replaced for a long time by a more efcient method. 4.6 The PGI Fortran compiler is no longer used to build Abinit under Windows, since it is too buggy. 4.6 Ultrix was an operating system based on a 4.2BSD Unix with some features from System V. It was rst released in 1984. Its purpose was to provide a DEC-supported native Unix for VAX. The last major release of Ultrix was version 4.5 in 1995, which supported DECstations and VAXen. There were some subsequent Y2K patches. There has been no ABINIT user on Ultrix quite some time.

PGIWin ultrix

24

Chapter 4 Adding external libraries / plug-ins

4.1 Overall procedure

For all the tasks to perform, just use the existing libraries as examples and tutorials as soon as you have a doubt. All paths are given from the top source directory. Please note that this procedure has been elaborated and complexied progressively and is now being reworked in order to greatly simplify it. 1. Create a new directory in lib/, with a short and explicit name. 2. Copy the tarball to the new directory and go there. Its name should be: <package name>.tar.gz. The package name may of course include a version number. 3. Create a RoboDOC header briey describing the library. The le should have the same name as the directory, plus leading and trailing underscores. Suggestion: copy the one from lib/netcdf/ and start from it. 4. Create a makele with the same name as the directory, plus a .mk extension. It will tell the build system how to perform the various steps of the library build: uncompress, congure, build, install. Suggestion: copy the one from lib/netcdf/ and use it as a starting point. 5. Create a abinit.amf le containing a list of additional les to clean. It will basically consists in the libraries, binaries, headers and Fortran modules used by ABINIT. Suggestion: use lib/netcdf/abinit.amf to see which is the format to follow. 6. Edit cong/specs/extlibs.cf : add one line for your library following the specied format. Put the most important module only in the second column if your library has several C/C++ headers or Fortran modules. The name of the library should be the same as for the directory. 7. Edit cong/specs/libraries.cf : a. in abinit libs, add the library after the others it could depend on and before the libraries depending on it; 25

26

Chapter 4. Adding external libraries / plug-ins b. in abilibs specs, copy the netcdf line, changing only its name and removing |ABI LIB INC if your library has no C/C++ header and no Fortran module; here the order is external/internal, then alphabetical, so you should add your library before the defs line; c. describe the dependencies in abilibs deps. The name of the library should be the same as for the directory. 8. Edit cong/specs/binaries.cf : add the library to the dependencies of every binary that may use it; the line should be put before the libraries it depends on and after the libraries that depend on it. The name of the library should be the same as for the directory. 9. Edit cong/specs/options.cf : add the --enable-* and --with-* options for your library, with short and precise info strings. Use netcdf as a typical example.

10. Edit cong.mk.in: add the build ags of the library at the end of the le. You may copy/paste from another external library, yet be careful to change ALL the references. 11. Edit cong/m4/tricks.m4: add a tricky macro at the end of the le. You may leave it empty, just as many of them already are. 12. Edit congure.ac: a. at the beginning, where external packages are declared; b. at the end, where the external library macros are called. Add the relevant information using what is there as examples. 13. Run cong/scripts/makemake, and watch carefully any possible error message. 14. Run congure, and watch carefully any possible error message. 15. Run make, and watch carefully any possible error message.

4.2

The library makele

The build system expects a few things from the makele <lib name>.mk managing the package stored in <package name>.tar.gz: it should include cong.mk, in order to transmit the build parameters to the packages own build system; it should uncompress in lib/<lib name>/<package name>, and thus move the uncompressed directory afterwards if it not the case (see lib/fox/fox.mk for an example); it should install in lib/<lib name>/tmp, so that the build system of ABINIT may import all required data by itself if the package is managed by the Autotools. Please read all the library makeles contained within ABINIT before writing yours, this might help you a lot. 26

4.3. Fine-tuning abinit.amf

27

4.3

Fine-tuning abinit.amf

Once you manage to build your library properly, run a make clean from within and add all remaining les that should have been swept off to the list contained in abinit.amf.

27

Part III Maintainers

29

Chapter 5 Extending the build system

5.1 Prerequisites

In order to efciently tweak the build system, you will need to have a good experience of some basic Unix utilities: cat, grep, sed, awk, cut, tr, tee, wc. A long familiarity with ABINIT and an active participation to the developments occuring within the last six months, though mandatory, will not sufce. You should already be uent in the following areas as well: Bourne-type shell scripting (http://en.wikipedia.org/wiki/Bourne shell); Perl scripting (http://en.wikipedia.org/wiki/Perl); Python scripting
(http://en.wikipedia.org/wiki/Python %28programming language%29);

M4 scripting (http://en.wikipedia.org/wiki/M4 %28computer language%29); Makele writing (http://en.wikipedia.org/wiki/Makefile); Link editing (http://en.wikipedia.org/wiki/Linker); Regular expression designing (http://en.wikipedia.org/wiki/Regular expression). Just as when developing for ABINIT, you will need a fully working installation of the GNU Autotools. And here is what distinguishes the maintainer from the developer: you will need to know how they work and understand their principles. Their respective documentations may be found at the following addresses: Autoconf http://www.gnu.org/software/autoconf/manual/

31

32

Chapter 5. Extending the build system Automake http://sources.redhat.com/automake/automake.html Libtool http://www.gnu.org/software/libtool/manual.html

We strongly urge you to read them if you want to know what you are doing. Last but not least, you will need to have Bazaar (http://bazaar-vcs.org/) installed on your development machine, since the delicate character of your contributions will require real-time interactions with other maintainers and/or developers, be it for bug xing or testing.

5.2

Adding scripts

If your extension inuences exclusively the pre-build stage of ABINIT, i.e. it prepares the way for the Autotools, you may add it in the form of a script in a binit/cong/scripts/. Please follow the conventions already adopted for the other scripts. When done, do not forget to add a call to your script in a binit/cong/scripts/makemake, and remember that makemake expects to be called from the top-level directory of the source tree. If your script is producing M4 macros, the names of the les containing them must be prexed by do-not-edit-.

5.3

Adding M4 macros

When you want to propagate information up to the Makeles of ABINIT, the recommended way to extend the build system is by writing M4 macros. The best practice is to create a new le in a binit/cong/m4/, following the conventions adopted for the other les. If at a later time your contribution is approved, it may be redispatched into other les.

5.4

Editing congure.ac

The congure.ac le is the spine of the build system. Every single character of this le plays a well-dened role, and is present for a carefully-thought logical reason. In particular, the order of the lines is of critical importance to the proper functioning of the whole build system. That is why this le should only be edited with extreme care by persons having a good knowledge of shell-scripts, M4, Autoconf, Automake, LibTool and the ABINIT build system. Messing-up with the instructions present there without a sufcient experience in these matters will for sure lead to catastrophic consequences, and may even result in massive loss of data. To summarise, YOU EDIT THIS FILE AT YOUR OWN RISKS. Believing you are more clever than the designers of the ABINIT build system will not save you. The congure script is generated from congure.ac by Autoconf. As such, congure should NEVER EVER been edited.

32