
HELP FILE FOR DEBUGGING ON THE BASIS OF "MAKE PARENTS"
======================================================

How to debug ?

Question 1 : if the error message is :
Error: Robodoc subroutine NAME missing in <dir/name_of_routine.F90>

Question 2 : if a section of the source file disappeared ?



------------------------------------------------------

* Question 1

After executing 
make parents
in the src directory, suppose you get an error message like the following :

Error: Robodoc subroutine NAME missing in <dir/name_of_routine.F90>

How to debug ABINIT ?


* Answer 1

The script parents relies heavily on the Robodoc-type structuration of the source file.
In particular, a source file should be made of sets of robodoc blocks, possibly separated
by comments or blank lines. 

In most of the source files, one block relates to a subroutine, typically :

!!****f* ABINIT/name_of_subroutine
!! NAME
!!  name_of_subroutine
<...>
 subroutine name_of_subroutine
<...>
!!***

The most common source of the above-mentioned error comes from the fact that
the parent.pl script expects the name_of_subroutine to be coherent in the three above occurrences...

For example, the following will generate an error

!!****f* ABINIT/blabla
!! NAME
!!  blabla
<...>
 subroutine blabla_int
<...>
!!***

It will be easy to correct this piece of code :

!!****f* ABINIT/blabla_int
!! NAME
!!  blabla_int
<...>
 subroutine blabla_int
<...>
!!***

Unfortunately, in some ABINIT source files, the number of such blocks can be large (bigger than 10),
and the above-mentioned error message does not mention the line where the error was found, neither
the subroutine for which there has been a mismatch. How to find the place where the error occurred ?

In the full list of messages obtained when executing 
make parent
one can find the list of block in this source file for which 
make parent 
succeeded. The suggestion is thus to examine the list of blocks or subroutines (e.g.  grep 'end subroutine'),
and proceed by elimination : the one that failed is the only one who did not succeed ...
Sorry if this procedure is not very nice...

------------------------------------------------------

* Question 2

How to debug if a section of the source file disappeared ?

* Answer 2

Well, it is likely that you have forgotten the keyword 
SOURCE
after the section CHLDREN ...
