How to add external libraries / plug-ins
========================================

Overall procedure
-----------------

For all the tasks to perform, just use the existing libraries as
examples and tutorials. All paths are given from the top source
directory. Please not that this procedure has been elaborated and
complexified progressively and is now being reworked for a great
simplification.

01. Create a new directory in "lib/", with a short and explicit name.

02. Copy the tarball to the new directory and go there. Its name should
    be: <package_name>.tar.gz. The package name may of course include a
    version number.

03. Create a RoboDOC header briefly describing the library. The file
    should have the same name as the directory, plus leading and trailing
    underscores. Suggestion: copy the one from "lib/netcdf/" and start
    from it.

04. Create a makefile with the same name as the directory, plus a ".mk"
    extension. It will tell the build system how to perform the various
    steps of the library build: uncompress, configure, build, install.
    Suggestion: copy the one from "lib/netcdf/" and use it as a starting
    point.

05. Create a "abinit.amf" file containing a list of additional files to
    clean. It will basically consists in the libraries, binaries, headers
    and Fortran modules used by ABINIT. Suggestion: use
    "lib/netcdf/abinit.amf" to see which is the format to follow.

06. Edit "config/specs/extlibs.cf": add one line for your library following
    the specified format. Put the most important module only in the second
    column if your library has several C/C++ headers or Fortran modules.
    The name of the library should be the same as for the directory.
    

07. Edit "config/specs/libraries.cf": 

        a. in "abinit_libs", add the library **after** the others it
           could depend on and **before** the libraries depending on it;
        b. in "abilibs_specs", copy the "netcdf" line, changing only its
           name and removing "|ABI_LIB_INC" if your library has no C/C++
           header and no Fortran module; here the order is
           external/internal, then alphabetical, so you should add your
           library before the "defs" line;
        c. describe the dependencies in "abilibs_deps".

    The name of the library should be the same as for the directory.

08. Edit "config/specs/binaries.cf": add the library to the dependencies
    of every binary that may use it; the line should be put **before** the
    libraries it depends on and **after** the libraries that depend on it.
    The name of the library should be the same as for the directory.

09. Edit "config/specs/options.cf": add the "--enable-*" and "--with-*"
    options for your library, with short and precise info strings. Use
    "netcdf" as a typical example.


10. Edit config.mk.in: add the build flags of the library at the end
    of the file. You may copy/paste from another external library, but
    be careful to change **ALL** the references.

11. Edit config/m4/tricks.m4: add a "tricky" macro at the end of the file.
    You may leave it empty, just as many of them already are.

12. Edit "configure.ac":

    a. at the beginning, where external packages are declared;
    b. at the end, where the external library macros are called.

   Add the relevant information using what is there as examples.

13. Run "config/scripts/makemake", and watch carefully any possible
    error message.

14. Run "configure", and watch carefully any possible error message.

15. Run "make", and watch carefully any possible error message.



The library makefile
--------------------

The build system expects a few things from the makefile "<lib_name>.mk"
managing the package stored in "<package_name>.tar.gz":

    - it should include "config.mk", in order to transmit the build
      parameters to the package's own build system;
    - it should uncompress in "lib/<lib_name>/<package_name>", thus move
      the uncompressed directory afterwards if it not the case (see
      "lib/fox/fox.mk" for an example);
    - it should install in "lib/<lib_name>/tmp", so that the build system
      of ABINIT may import all required data by itself if the package is
      managed by the Autotools.

Please read all the library makefiles contained within ABINIT before
writing yours, this might help you a lot.



Fine-tuning "abinit.amf"
------------------------

Once you manage to build your library properly, run a "make clean" from
within and add all remaining files that should have been swept off to the
list contained in "abinit.amf".

