Please read the Conventions and formatting page at least once before everything else.

• installing-abinit.pdf

The configure script is a portable shell-script generated by Autoconf from a file called configure.ac or configure.in. It contains a sequence of commands depending on the software package it belongs to and the purpose of which is to detect the components needed to build this package.

The commonly-accepted default behavior is that the configure script should be able to provide working build parameters when run without option. However, to let users customize interact with it and customize its behavior, Autoconf provides a mechanism to transmit command-line options to configure. There are 2 kinds of options:

• switches, to turn simple features on and off, available through the enable_* shell variables and --enable-* / --disable-* on the command line;
• optional packages, to enable or disable support for external dependencies and complex features, available through the with_* shell variables and --with-* / --without-* on the command line.

In addition, the configure script comes with built-in standard options to customize the installation of the package and lets the developers mark some environment variables as important.

To obtain the full list of available options and their documentation, just type:

./configure --help

from the top source directory of any Autoconf-powered software package. With Abinit, you will get a long list of options and environment variables. Reading it at least once is a very good way to become aware of the possible optimizations offered at configure-time and get some familiarity with the underlying philosophy of the build system.

If you have run the ./configure --help command, you will have already noticed that Abinit can be configured through various environment variables. A few others, not listed by configure, are also of great importance, and we will describe them in this section.

Setting an environment variable is usually done using the variable name directly, e.g.:

LD_LIBRARY_PATH="/opt/my_package/lib"

while querying it is done by prefixing its name with a dollar sign, e.g.:

echo $LD_LIBRARY_PATH

Quite often, the situation happens to be a mix of both, e.g.:

export LD_LIBRARY_PATH="/opt/my_package/lib:$LD_LIBRARY_PATH"

The PATH environment variable tells the system where to look for relevant programs. It consists in a column-separated list of directories containing executable files. The following is a typical value that can be obtained from the command line:

$ echo $PATH
/home/abinit/bin:/usr/local/bin:/usr/bin:/bin

The configure script looks for various programs, in order to decide which features should be enabled and which ones not. In particular, if you use Abinit Fallbacks, you should make sure that your PATH contains the directory containing the abinit-fallbacks-config program before running configure, e.g.:

$ export PATH="/fallbacks/install/directory/**bin**:$PATH"

Equally essential, LD_LIBRARY_PATH is to libraries what PATH is to programs, and works exactly the same: it is a column-separated list of directories containing shared libraries. On Unix systems, these libraries have a “.so” extension. On MacOS, their extension is “.dylib”. On windows, it is “.dll”. A typical setting with a strict Bourne Shell is:

$ LD_LIBRARY_PATH="/path/to/abinit/dependency/**lib**:$LD_LIBRARY_PATH"
$ export LD_LIBRARY_PATH

Please note that LD_LIBRARY_PATH is called DYLD_LIBRARY_PATH on MacOS.

If you use GCC compilers, you may sometimes want to use the LIBRARY_PATH environment variable as well, in particular if the build fails while LD_LIBRARY_PATH has been correctly set. Contrary to the latter, LIBRARY_PATH is only used by the compiler at link-time and will be ignored when running an Abinit executable.

Python is usually installed by system administrators in a standard way on most computers. However, if you use custom Python modules that you have installed yourself, please make sure that the PYTHONPATH variable is properly set before configuring Abinit.

From time to time, some compilers complain or do not display important messages because language support is improperly configured on your computer. Should this happen, we recommend you to type the following:

$ LANG=C; LC_ALL=C
$ export LANG LC_ALL

This will reset the language support to its most basic defaults and will make sure that you get all messages from the compilers – in English, of course.

We strongly recommend you to systematically use a build directory different from the source tree when compiling Abinit. Usually, this is done by creating a new subdirectory at the top of the Abinit source tree and is as simple as typing:

cd ~abinit && mkdir my_build_dir && cd my_build_dir && ../configure

Besides being a standard way to proceed with most Autotools-based software packages, this is much cleaner than building directly in the source tree, since it clearly separates the built files from the source files and keeps the latter untouched. If your build fails for any reason, you can always restart with the guarantee of a pristine source tree by simply removing the contents of the build directory or creating a new one.

If you wish, you can even build Abinit fully outside its source tree by creating a build directory anywhere and using the --srcdir option of configure.

When using some options repeatedly, it quickly becomes tedious to type them again and again on the command line. On the other hand, if you only compile Abinit once in a while, you will likely forget the options that you used previously between 2 builds. This is why we provide an alternative way to provide options to the configure script, through the use of config files.

In order to accommodate as many situations as possible, we have designed a flexible mechanism to handle config files:

• first, the build system looks into the build directory for a config file, which lets you import parameters for a specific build;
• if not found, it looks into the source directory, which allows you to use build parameters related to a particular version of Abinit;
• if still not found, it looks into the ~/.abinit/build/ directory, which acts as a provider of default parameters corresponding to your particular preferences;
• finally, it looks into the /etc/abinit/build/ directory, to let system administrators provide system-wide parameters for a specific computer.

Of these 4 possibilities, the first file encountered is processed and the build system goes on without looking for more files. In other words, config files are not cumulative. For example, if a user has a ~/.abinit/build/my_host.ac, the system-wide defaults found in /etc/abinit/build/my_host.ac will always be ignored.

Since many developers of Abinit work on shared filesystems, the build system looks by default for a file called `hostname`.ac, where `hostname` represents the result of the following command, that you can type in a shell to know how to name your config files (do not type the dollar signs):

$ hostname
wiki
$ 

In the current example, you would name your config file wiki.ac if you want the build system to take it into account by default.

This operation has to be repeated once on every computer where you want to build Abinit using a config file. We chose this strategy to make sure that the build system will always take the correct config file even in the case several computers would share the same home directory.

You will find detailed instructions on how to set the various options of the configure script in the template file ~abinit/doc/build/config-template.ac, including how to have your config file included automatically each time you build Abinit. There are only 2 undocumented options in this template:

• the --with-config-file option, which lets you use arbitrary names for your config files, as long as you specify it each time on the command line;
• the --disable-config-file option, to force Abinit not to use any config file.

For obvious reasons, they are the only options that cannot be stored in a config file.

The build system of Abinit is quite modular and is composed of logical blocks addressing each a specific configuration issue. The following documents will help you tune the build parameters depending on what you want to adjust.

Configuring compilers helps you select C, C++ and Fortran compilers, and find the best compromise between performance and reliability for your architecture. It includes a section on preprocessors and the corresponding platform-specific issues.

Configuring multicore architectures shows how to configure OpenMP-, MPI-, and GPU-enabled architectures, as well as how to force a build to remain serial.

Configuring linear algebra explains how to configure linear algebra support for your particular situation.

Configuring Fast Fourier Transforms guides you to select the best FFT algorithm for your particular situation.

Configuring feature triggers provides you with useful advice on how to enhance the capabilities of Abinit with external packages.