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

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 a version of PYTHON 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 e.g. for 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.

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.

Coming soon …

OpenMP, MPI, GPU, …

Linear algebra is the most critical dependency to consider, since Abinit could not build nor run without it. It is also the most complex one, due to:

• the different components to select and their various interactions with external factors, e.g. using ScaLAPACK only makes sense if your environment supports MPI;
• the way each component is provided, e.g. one component per library or all components in one library;
• the tremendous diversity of the available implementations.

It corresponds to the most complex component of the build system. Take your time to read this section and feel free to come back as many times as you wish.

The following table summarizes the linear algebra components supported by Abinit:

By default, the build system assumes that you want the fastest possible linear algebra operations. When no linear algebra option is specified, it thus looks for each component as soon as its prerequisites are met. The only required components are BLAS and LAPACK, since Abinit relies on them in each and every situation. The other components are enabled only if their prerequisites are met, their detection succeeds, and are proved working.

To deal more easily with the various linear algebra implementations that can be used concurrently on the same computer, Abinit provides the with_linalg_flavor option. It will tune the detection tests made by the build system so that the probability of finding the correct libraries and setting-up the environment is maximized.

You can tune the detection mechanism through the with_linalg_flavor option in 3 ways:

• by just specifying a plus-separated list of flavors, in which case the build system will figure out how to assign which flavor to which component;
• architecture-wise, by specifying a comma-separated list of arch:value statements, where arch can be serial, openmp, mpi, or gpu, and value is a plus-separated list of flavors;
• component-wise, by specifying a comma-separated list of component:value statements, where component is one of the keywords from the first column of the above table, and value is a corresponding flavor – only one is permitted in this case.

Please note that you can only use one of these 3 methods at a time. Mixes are explicitly forbidden. Omitting an architectural item or a linear algebra component with the 2 latter methods will be equivalent to disabling this element.

Example 1:

with_linalg_flavor="openblas+netlib"

will cause the build system to look for OpenBLAS for the blas component and use Netlib for the other ones, i.e. lapack for the serial case and scalapack if MPI is enabled in the current build. Unspecified components will be detected using the default behavior, e.g. the build system will look for all available implementations of elpa if MPI is enabled but do nothing if MPI is disabled.

Example 2:

with_linalg_flavor="serial:atlas+netlib,mpi:netlib,gpu:magma15"

will cause the build system to look for Atlas for blas, Netlib for lapack and scalapack, and MAGMA 1.5 for magma. However, it will never look for elpa, since it has not been explicitly stated, and will stop with an error if one of the specified elements is not present or not working. When using this method, you must specify the serial block and make sure its value will provide the blas and lapack components.

Example 3:

with_linalg_flavor="blas:atlas,lapack:netlib,elpa:elpa2015"

will cause the build system to look for the blas, lapack and elpa components, but not for scalapack, even if MPI is enabled. It will also fail if any component is missing or not working. When using this method, you must specify the blas and lapack components.

The other options provide hints to the build system and determine which kinds of tests will be performed:

• with_linalg_fcflags defines which Fortran compiler flags should be applied at compile time; this is useful for compilers providing native linear algebra support;
• with_linalg_ldflags defines which flags should be passed to the linker when building programs; this is useful for compilers providing native linear algebra support;
• with_linalg_incs defines which include flags should be applied at compile time; this option is only useful for LAPACKe;
• with_linalg_libs defines which libraries should be linked with the programs performing linear algebra operations.

The capabilities of Abinit can be enhanced by the use of optional external packages. The corresponding options of configure all follow the same scheme:

• enable_package, to trigger the detection and build of the corresponding feature;
• with_package, to specify the install prefix of a package;
• with_package_bins, to specify where to look for the executables of a package (when applies);
• with_package_incs, to specify include flags when compiling code that uses the package (when applies);
• with_package_libs, to specify package libraries to link the code with (when applies).

In each of the previous items, package will be replaced by the names listed below. Please note that the use of with_package is incompatible with the other with_* options, since it defines the values specified by these options in a possibly conflicting way. If you try to use both schemes, configure will fail and ask you to choose only one of them.

The with_package option expects a directory as argument. For example, if you specify:

with_fox="/path/to/fox"

, the configure script will look for:

• binaries in /path/to/fox/bin;
• include files in /path/to/fox/include;
• libraries in /path/to/fox/lib and /path/to/fox/lib64.

The following table summarizes the available optional features of Abinit. To enable them, you will have to make sure that the corresponding external dependencies of Abinit are correctly installed on your system before configuring Abinit.

The following table indicates which options are allowed for each package and whether it is enabled by default. For purely optional packages, the default is to disable them, whereas packages transitioning from optional to mandatory are usually enabled by default. In the following, to determine the names of the options, just replace the stars by the corresponding package IDs.

For instance, LibXC support is enabled by default, and there are with_libxc, with_libxc_incs, and with_libxc_libs options, but there is no with_libxc_bins option.

All these options cen be overridden by with_extdeps_prefix, which tells the configure script that all external dependencies have been installed in the same place. This option is mutually exclusive with the use of any other with_* option for optional features. If you decide to use it, it must be the only one.

Coming soon …

Coming soon …