HOWTO obtain native Fortran90, C and Python bindings for ABINIT parser
======================================================================

1. Generate a description of the dataset structure.
2. Tune the variables (compiler, macros, paths).
3. Compile the bindings.


1. Generate a description of the dataset structure
--------------------------------------------------

Normally this first point is done automatically by the Makefile. If not,
here are the details.

There are five generated files in this directory:

  - ab7_invars.h: contains the public C headers including the ids
    of all dtset attributes;
  - ab7_invars_c.h: contains the types of all dtset attributes (private
    use);
  - ab7_invars_py.h: the same for the Python bindings.

They are generated using the config/scripts/make-sources-parser Python
script that reads a pickle file generated by abilint. To generate the
pickle file from abilint use from the root of source tree:
*/*/abilint --dump_dtset src/bindings/dtset.pickle . .
This pickle should have been generated automatically by the makemake
script of ABINIT.


2. Tune the variables (compiler, macros, paths)
-----------------------------------------------

All sources have been set and tested for Gfortran.
To compile with other compilers, one need to change
bindings/parser/ab7_invars_c.c and modify the FC_MOD_NAME macro to the
adequat naming scheme of the compiler. Here is a list of known schemes:

  - g95:          FC_MOD_NAME(M,A) M ## _MP_ ## A
  - gfortran 4.2: FC_MOD_NAME(M,A) __ ## M ## __ ## A
  - gfortran 4.3: FC_MOD_NAME(M,A) __ ## M ## _MOD_ ## A
  - ifort:        FC_MOD_NAME(M,A) M ## _mp_ ## A ## _

The same modifications should be applied to the ab7_symmetry_c.c file.
For the Python bindings, one also need to change the FC_FUNC macro of file
src/bindings/ab7_invars_py.c. This should be handled automatically later by the
configure script (volunteers needed).


3. Compile the bindings
-----------------------

To compile the bindings, currently, one should do the following:

  - configure with gfortran and add the flag -fPIC for 64bits machines.
    To compile with other compilers, see above. The flag --enable-bindings
    must be passed also to the configure.
  - compile ABINIT normally, specifically the src/libs directory.
  - go to bindings/parser and issue 'make'. Issue
    'make -f parser.mk python' to build the Python bindings only.
  - in the same directory, one can also 'make -f parser.mk check'.
    It will compile examples and check that they run as references.
    If no complains, it means success.
  - to test the Python bindings, one need to have ElementTree.py and
    ElementPath.py. Then, issue ./gtkParse.py (read the following warning
    before).

WARNING! With the gfortran compiler, the gtk interface does not work.
         It is a bug in gfortran when the locale is not C. So set
         LANG=C before testing gtkParse.py.
