The ESL Bundle is a collection of libraries and utilities broadly used in
electronic structure calculations, put together to make their use easier by
researchers and scientific software developers. It includes a building framework
helping users, developers and packagers in obtaining a working installation of
complex combinations of software packages without having to track the
dependencies themselves.
ESL stands for Electronic Structure Library, an initiative which distributes quality software and promotes open standards for high-performance computing applications in the field of electronic structure calculations. More details can be found on the ESL Wiki.
To work properly, the ESL Bundle requires Python 3.x but still works with
Python 2.7 for now. Fortran, C and C++ compilers are also required, as most
modules are written in one or more of these programming languages. Some modules
also provide bindings for other languages. Depending on the modules you wish to
build, some additional packages might be required. These are packages that are
found in most Linux distributions and/or commonly available in HPC facilities,
and therefore it was not deemed necessary to include them in the ESL
Bundle.
Some modules support parallelization through MPI. A working MPI installation is necessary to build modules with MPI support.
This is a complete list of packages included in the ESL Bundle.
The ESL Bundle comes with a version of JHBuild which has been tuned to
fit the context of the ESL. JHBuild supports a wide variety of build
systems, although it is not a build system itself. It is rather a tool designed
to ease the build of collections of related source packages, that it calls
"modules". It was originally written for the Gnome Project, but its use has
then been extended to other situations.
To make the use of JHBuild easier in the context of the ESL Bundle, we
provide a wrapper script called install-bundle that can be found in the
top source directory of the bundle. Most of the operations are performed by
executing this install-bundle script with appropriate parameters. The
command line syntax is the following:
install-bundle [global-options] [package(s) ...]
The following global options are available and can be shown running the following command from the top source directory of the bundle:
./install-bundle -h
In particular, this command shows the currently possible values for each of the options:
- -c, --compilers VENDOR: Use compilers from VENDOR instead of the default (gcc).
- -f, --flavor FLAVOR: Use the build parameters corresponding to FLAVOR (usually a MPI implementation) instead of the default (serial).
- -m, --moduleset NAME: Use the module set NAME instead of the default (esl). Please note that some module sets are still under development (abinit, siesta).
- -s, --system SYSTEM: Use the operating system or Linux distribution labelled SYSTEM instead of the default (generic).
- --exit-on-error: Exit immediately if a module fails to build instead of continuing with other modules.
- --no-interact: Do not prompt the user for any input. This option is useful if leaving a build unattended, in order to ensure that JHBuild will not prompt the user for input.
- --conditions ARGS: Change the way modules are built according to ARGS instead of the defaults. ARGS can be specified as e.g. +no_elpa (to skip the build of ELPA) or +yaml (if libyaml is missing on your system). This feature is still experimental and provides the above-mentioned examples only for now.
In the ESL Bundle, the default module set is esl. It provides a
meta-module called esl-bundle, which builds and installs all the packages
included in the bundle. A second meta-module, called esl-bundle-mpi, is
provided to build the packages with MPI support. Note that not all packages
can be compiled with MPI support. In that case they will be built without it.
The install-bundle script does not need to be invoked from the directory
where it is located.
Note
To keep the source directory clean, we highly recommended the use of a build directory.
Therefore, a typical way of installing the collection of ESL libraries is the following:
mkdir my_build_dir cd my_build_dir ../install-bundle
By default, the build command will compile all the modules from the
esl-bundle meta-module and install them in the current directory. This, and
a few other options, can be changed using configuration files. Several sample
configuration files are provided in the rcfiles/ subdirectory. These files
should be suitable to build the bundle in a variety of systems, but they can
also be used as a starting point to write configuration files more suited to
your needs.
If you want to use the install-bundle script with your own config files,
please follow the naming convention SYSTEM-VENDOR-FLAVOR.rc, where:
SYSTEM is the operating system or Linux distribution the file is meant for,
or generic if it does not matter; VENDOR is the vendor of the C, C++ and
Fortran compilers used to build the packages; FLAVOR is the MPI
implementation to use, or serial if there is none. If you add support for a
new compiler vendor, please create a file named generic-VENDOR-serial.rc
with the corresponding options, else the install-bundle script will
complain.
The configuration files use Python syntax. Here is a list of some important options:
modules: dictionary of modules to build.prefix: directory where the modules should be installed.checkoutroot: where to unpack the module's sources.
Configuration options to be passed to the modules build systems can also be specified in the configuration file. Here is an example of how to do this:
# Set the FC variable when invoking the configure script for all modules autogenargs="FC=gfortran" # Run make in parallel with two threads makeargs="-j2" # Here the futile module requires an extra configuration option. # Note that this will overwrite the global options set by autogenargs, so we # have to add it here explicitly. module_autogenargs['futile'] = "--with-ext-linalg='-lopenblas' " + autogenargs
The ESL Bundle provides pkg-config files for all the modules. These can be
used to make the installed packages available to other applications.
To use this feature, a working installation of pkg-config is necessary. To make the installed packages available to other applications, the most important is to set the PKG_CONFIG_PATH environment variable. For a Bourne-like shell, the command is:
export PKG_CONFIG_PATH="/path/to/esl-bundle/my_build_dir/install/lib/pkgconfig:${PKG_CONFIG_PATH}"
- while for a C-like shell it is::
- setenv PKG_CONFIG_PATH "/path/to/esl-bundle/my_build_dir/install/lib/pkgconfig:${PKG_CONFIG_PATH}"
where you replace /path/to/esl-bundle/my_build_dir by the full path to your
actual build directory.
Provided the application you wish to build is aware of pkg-config, this command will let it automatically configure all the libraries it needs to build and run.
Note
Please read the pkg-config documentation on how to use pkg-config to compile your application.