Including...and excluding certain files?

[mathomp4]

So this is a question for the FORD Gurus. Once @ZedThree helped me get my test runs of FORD on MAPL (my library), I noticed something. As I was trying to remove all the warnings from my runs of FORD, I saw these:

Reading file ../Tests/ExtDataDriverGridComp.F90
Preprocessing /Users/mathomp4/Ford-Doxygen-Protex/MAPL/Ford/../Tests/ExtDataDriverGridComp.F90
WARNING: Can not find include file "mpif.h".
...
Reading file ../MAPL_cfio/ESMF_CFIOBaseMod.f
Warning: Error parsing ../MAPL_cfio/ESMF_CFIOBaseMod.f.
	Can not find include file "netcdf.inc".
Reading file ../MAPL_cfio/ESMF_CFIOUtilMod.F90

say, or even this:

Reading file ../gridcomps/Cap/MAPL_NUOPCWrapperMod.F90
Preprocessing /Users/mathomp4/Ford-Doxygen-Protex/MAPL/Ford/../gridcomps/Cap/MAPL_NUOPCWrapperMod.F90
Warning: error when preprocessing /Users/mathomp4/Ford-Doxygen-Protex/MAPL/Ford/../gridcomps/Cap/MAPL_NUOPCWrapperMod.F90:
/Users/mathomp4/installed/Core/gcc-gfortran/11.3.0/bin/cpp -traditional-cpp -E -DUSE_MPI=1 -DBUILD_WITH_PFLOGGER=1 -DBUILD_WITH_EXTDATA2G=1 -DUSE_FLAP=1 -I/Users/mathomp4/Ford-Doxygen-Protex/MAPL/Ford/../include -I/Users/mathomp4/Ford-Doxygen-Protex/gFTL/install-gcc-gfortran-11.3.0/GFTL-1.8/include/v1 -I/Users/mathomp4/Ford-Doxygen-Protex/gFTL/install-gcc-gfortran-11.3.0/GFTL-1.8/include/v2 /Users/mathomp4/Ford-Doxygen-Protex/MAPL/Ford/../gridcomps/Cap/MAPL_NUOPCWrapperMod.F90
/Users/mathomp4/Ford-Doxygen-Protex/MAPL/Ford/../gridcomps/Cap/MAPL_NUOPCWrapperMod.F90:62:2: fatal error: mpif.h: No such file or directory
   62 |
      |  ^
compilation terminated.

Reverting to unpreprocessed file

So, I decided, okay, let's go add them to my include:

include: ../include/
         /Users/mathomp4/Ford-Doxygen-Protex/gFTL/install-gcc-gfortran-11.3.0/GFTL-1.8/include/v1
         /Users/mathomp4/Ford-Doxygen-Protex/gFTL/install-gcc-gfortran-11.3.0/GFTL-1.8/include/v2
         /Users/mathomp4/installed/Compiler/gcc-gfortran-11.3.0/openmpi/4.1.3/include
         /Users/mathomp4/installed/MPI/gcc-gfortran-11.3.0/openmpi-4.1.3/Baselibs/7.0.0/Darwin/include/netcdf

And this worked. All the warnings went away. 🎉

But there was a side-effect. On some of the documentation pages, say those files that use #include mpif.h, I now get a page that is probably 95% MPI documentation (common blocks, variables, and interfaces) and waaaaaay down at the bottom was the stuff I cared about. (Though I guess I've learned that MPI_BOTTOM is in a COMMON block.

So I wondered, is there a way to tell FORD to include these files when it comes to preprocessing, but also exclude them from the resulting documentation?

(Note: I know the correct answer is probably "Convert to use mpi" and that's probably what I want to do long-term, but for now...)

[ZedThree]

I'm afraid there's currently no mechanism for dealing with this. When the files are preprocessed, the text of the #include files is literally included, so ford has no way of knowing that some part of the file came from somewhere else.

Converting to use mpi is definitely one option, but speaking from experience, for large projects, this is not exactly trivial.

Something that we could add to ford might be special comments like this:

!! ford off
#include "mpi.h"
!! ford on

which would tell ford to handle that region like an external module or something. I've not thought this through very much, but something like that might be possible

[mathomp4]

I'm afraid there's currently no mechanism for dealing with this. When the files are preprocessed, the text of the #include files is literally included, so ford has no way of knowing that some part of the file came from somewhere else.

Converting to use mpi is definitely one option, but speaking from experience, for large projects, this is not exactly trivial.

Something that we could add to ford might be special comments like this:

!! ford off
#include "mpi.h"
!! ford on

which would tell ford to handle that region like an external module or something. I've not thought this through very much, but something like that might be possible

@ZedThree Thanks for confirming. For now, as long as FORD doesn't choke on the warnings when the preprocessor can't find these files, I think I'm happy. I mean, it seems to do okay in my testing:

https://mathomp4.github.io/MAPL/sourcefile/mapl_nuopcwrappermod.f90.html

and I see no need to subject people to Fortran 77 interfaces.

MAPL_NUOPCWrapperMod.F90 – MAPL

MAPL is a foundation layer of the GEOS architecture, whose original purpose is to supplement the Earth System Modeling Framework (ESMF)

[loiseaujc]

Hej,

Any chance you guys thought more profoundly about this !! ford off / !! ford on thing ? I want to use ford for documenting an extension I have been writing for an f77 computational fluid dynamics code. I have a bunch of include 'SIZE' statements, where SIZE is a file from this other project defining a bunch of variables. Whenever I run ford, I however get

Reading file core/matvec.f
Warning: Error parsing core/matvec.f
                  Can not find include file "SIZE"
Error: No source files with appropriate extension found in specified directory.

and I am not sure how to find my way around.