E.1 Adding Optional Libraries into FHI-aims: Stubs

The optional presence or absence of certain libraries from FHI-aims at compile time means that the main FHI-aims code must be able to deal with the possible absence of certain subroutine or function calls to those libraries at compile time.

In many codes, this is handled by adding preprocessor statement. In FHI-aims, preprocessor flags are NOT the way forward. The simple reason is that a single preprocessor flag may remain understandable for an ordinary user; the proliferation of ten or more preprocessor flags will create a serious obstacle for others to obtain a reasonably compiled code. Code that introduces preprocessor statements into FHI-aims will be removed from the code base.

In FHI-aims, the recommended way to optionally add or circumvent a given library is by creating a “stub” file for those library calls – essentially, empty subroutines that inform a user that they should not have ended up here with a given version of the code (i.e., without linking to a certain external library). At compile time, an appropriate flag in the Makefile and Makefile.backend should be created that switches between the real external library (if available) or the “stub” file. Please follow the example of “libxc” etc. in the “CMakeLists.txt” file, the Makefile, and Makefile.backend for more information. The principle is simple and easy to apply for any other optional library.