* NOTE: compatibility of allocation, timing, and error reporting handlers

This version removes the need to link external handlers for those operations, and
provides built-in default versions. If custom functionality is needed, client programs
can use setter routines that will install appropriate procedure pointers in libgridxc.
(See setter names in src/gridxc.F90 and interface information in the appropriate files)

==========================================================

You have three options to compile the library, one based on
auto-tools, another on CMake, and the third on a 'home-grown' building
system.

A. With the standard 'configure' route. Both serial and
   parallel versions can be built in the same hierarchy
   with the '--enable-multiconfig' option:

   What follows is a minimal sketch. Type

            configure --help

   for more information.

   NOTE: In some systems (e.g., with some Intel-compiler
   installations), libgridxc has to be built with the option
   '--disable-shared' if libxc was not built with shared libraries, or
   viceversa.  The libxc default is *not* to create shared libraries,
   and the libgridxc default is to create them...
   Probably the best route is to compile libxc with '--enable-shared'.
   Then the following examples should work out of the box.
   
  * Serial version:

  mkdir build_serial
  sh ../configure --enable-multiconfig \
                  --without-mpi --with-libxc=$LIBXC_ROOT \
                  --prefix=/path/to/installation/directory

  make
  make check
  make install

  * Create a building directory for the parallel version:

  mkdir build_mpi
  FC=mpif90 CC=mpicc ../configure --enable-multiconfig \
          --with-mpi=/path/to/mpi/dir --with-libxc=$LIBXC_ROOT \
          --prefix=/path/to/installation/directory

  make
  make check
  make install

  Then, in /path/to/installation/directory you will have, among
  other things:

  lib/libgridxc_dp.a
  lib/libgridxc_dp_mpi.a
  include/gridxc_dp
  include/gridxc_dp_mpi

  etc.

  This can be automated (and extended to the single-precision version
  of cellxc functionality) by the use of the 'multiconfig-build.sh' script.
  
B. With CMake

A single version of the library will be installed, with features
determined by the settings of the options (defaults shown):

  option(WITH_MPI "MPI-parallelism" FALSE)
  option(WITH_GRID_SP "Single-precision (cellxc only) interface" FALSE)

For example, a double precision MPI version can be built and installed with

  cmake -S. -B_build -DWITH_MPI=ON -DCMAKE_INSTALL_PREFIX=/path/to/installation
  cmake --build _build
  cmake --build _build --target test  # Optional
  cmake --install _build


In addition, libxc support can be enabled with -DWITH_LIBXC=ON, and
the location of libxc should be added to the search path:

  CMAKE_PREFIX_PATH=$LIBXC_ROOT cmake -S. -B_build -DWITH_MPI=ON
      -DWITH_LIBXC=ON -DCMAKE_INSTALL_PREFIX=/path/to/installation

Docs (generated by FORD) can be built by setting:

  cmake ... -DLIBGRIDXC_BUILD_DOCS_FORD=ON

assuming the ford program is available.
(See https://github.com/Fortran-FOSS-Programmers/ford)

* Compiling user programs using the CMake-installed version

Just use the standard CMake idiom in your CMakeLists.txt file:

    add_executable(your_program your_sources)
    find_package(libgridxc REQUIRED)
    target_link_libraries(your_program libgridxc::libgridxc)

The above assumes that the installation directory for libgridxc can
be found by CMake. This can be achieved by adding it to the CMAKE_PREFIX_PATH
CMake or enviroment variable:

    cmake -S. -B_your_build -DCMAKE_PREFIX_PATH=$GRIDXC_ROOT .......
    CMAKE_PREFIX_PATH=$GRIDXC_ROOT cmake -S. -B_your_build .......

NOTE: For the full logic of finding a variety of libgridxc versions,
      features, and installation flavors, please see Siesta's CMake scripts
      (https://gitlab.com/siesta-project/siesta)

C. With the legacy 'home-grown' building system
   (NOTE: This method, while useful, might be deprecated soon)

* Create a building directory at the top level. For example:

  mkdir Gfortran
  
* Create a fortran.mk file along the lines of the sample provided in
  the 'extra' directory and put it in the building directory.
  Make sure that you define the symbol FC_SERIAL (instead of just FC)
  to point to your standard fortran compiler. If you plan to build the
  parallel version of the library, define also FC_PARALLEL to point to
  your MPI wrapper (typically mpif90).

* Type, from the building directory

     sh ../src/config.sh

  to populate the building directory with makefiles and other
  supporting files. Home-grown makefiles in the 'src' and 'Testers'
  directories have an '.alt' suffix to avoid clashes with the
  auto-tools automatically-generated files.

* Installation is now handled by the build.sh script:

     sh build.sh

  will install a serial version of the library locally.

    PREFIX=/path/to/installation sh build.sh

  will install a serial version in $PREFIX
  
* It is suggested to install two versions of gridxc, serial and
  parallel, in two subtrees of an installation tree.
  The 'build.sh' script can handle that automatically. For example:

    WITH_MPI=1 PREFIX=/path/to/installation sh build.sh

  (see full details in the src/build.sh script itself)
  This assumes that your MPI installation includes a 'mpif90' wrapper
  compiler.  This is the easiest option. Otherwise you will have to
  define the MPI_INCFLAGS variable in the fortran.mk file, and
  possibly other things.


* To include libXC support, define the LIBXC_ROOT variable pointing to
  the top of your libxc installation. You can do this in the makefile itself,
  or elsewhere (e.g., in an environment module).

  Compilation has been tested with libxc-2.2.3, libxc-3.0.0,
  libxc-4.3.4, and libxc-5.1.5. Interface changes across versions, if
  any, are dealt with automatically through pre-processed code that
  checks the libxc version information. The contents of the
  src/libxc.mk file are appropriate for versions 4.X and above. For
  versions below 4, the appropriate file is libxc-prev4.mk (this is
  handled automatically by the build.sh script).  If relevant details
  (e.g. the names of the libraries) change in future versions of libXC
  these files should be updated.

  Then, use 'WITH_LIBXC=1' in the invokation of 'make'. For example:
  
      WITH_LIBXC=1 PREFIX=/path/to/installation sh build.sh

* To include both MPI and LIBXC support, use:

      WITH_LIBXC=1  WITH_MPI=1 PREFIX=/path/to/installation sh build.sh

==============================

To use GridXC in your program:
   
*) If you used the autotools route to building, you can use the
   pkg_config tool to determine the include directories and library
   flags needed:

   export PKG_CONFIG_PATH=$GRIDXC_ROOT/lib/pkgconfig:$LIBXC_ROOT/lib/pkgconfig
   pkg-config --libs libgridxc_dp
   pkg-config --cflags libgridxc_dp
   
   
   Or manually, define, for example (for a _dp flavor
   installed with --enable-multiconfig):

     GRIDXC_INCFLAGS= -I/path/to/installation/include/gridxc_dp
     GRIDXC_LIBS= -L/path/to/installation/lib -lgridxc_dp \
                  -L/path/to/libxc_installation/lib -lxcf90 -lxc

   
*) If you used the legacy route to building, include in your makefile
   $(GRIDXC_ROOT)/gridxc.mk, where GRIDXC_ROOT points to the root of
   your installation of libGridXC. This will define the symbols:
   
     GRIDXC_INCFLAGS
     GRIDXC_LIBS

   that can be used to have the compiler search the right places for
   the appropriate modules and libraries. To use the MPI version of
   the library, the symbol WITH_MPI=1 should be set at the time of the
   inclusion of the gridxc.mk file. For example:

     GRIDXC_ROOT=/path/to/installation WITH_MPI=1 make ....

   If you are using libxc, define the variable LIBXC_ROOT so that it
   is available to the building process. The libxc module files and
   libraries will be picked up automatically. Care should be taken
   to have LIBXC_ROOT point to *the same* libxc installation used
   when libgridxc was compiled. This can be achieved easily through
   environmental modules with proper dependencies.

   (the .mk files route to discovery of symbols is also available
    with an autotools-installed library, but in this case the .mk
    files are installed in $(GRIDXC_ROOT)/share/org.siesta-project)
    
   Alberto Garcia
   albertog@icmab.es
