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.
==
Normally this first point is done automatically by the Makefile. If not,
here are the details.

There are five generated files in this directory:
- ab6_invars.h: contains the public C headers including the ids
  of all dtset attributes.
- ab6_invars_c.h: contains the types of all dtset attributes (private use).
- ab6_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.
==
All sources have been set and tested for Gfortran.
To compile with other compilers, one need to change bindings/parser/ab6_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 ab6_symmetry_c.c file.
For the Python bindings, one also need to change the FC_FUNC macro of file
src/bindings/ab6_invars_py.c. This should be handled automatically later by the
configure script (volunteers needed).

3.
==
To compile the bindings, currently, one should do:
- 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 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.
