Suggestion: Create include directory about grid

[paboyle]

Hi Guido,

I'm always torn on this; personally I like to have the .cc source physically beside the corresponding .h headers. This is what Chroma does, for example and it is one of two obvious conventions.
Whether we call "lib" lib or rename it simple "src" is something have worried about a bit.

My view is partly because, as with say boost, in a template library you end up with most of the library
in headers in the end, with the idea that there can be separation of implementation and interface into src and include trees is perhaps broken?

i.e. templates force header availability of implementation and not just interface so that they
can be compile time instantiated.

[mspraggs]

Having separate source/include files makes some sense if your aim is to export a clean interface for others to use, as it's then easier for users to examine the interface without wading in amongst a bunch of source files.

However, I absolutely understand the desire to put sources and headers together, as for one thing it makes code navigation easier if you're the one maintaining the package. I also understand what Peter's saying, in that much of the code is templated so source files almost become irrelevant.

Actually, on that point, what is sometimes done is to put the implementation into a separate file, sometimes suffixed with .inl, then this is included at the bottom of the header. This way the header isn't cluttered with the implementation, but still "contains" it, so the compiler can instantiate it. I think boost libraries often have something like a "detail" directory where they bung this sort of thing.

[paboyle]

The big issue for me is that it is easier to maintain with the .c and .h together. I get driven crazy
by switching directories in other packages, (like UKhadron which I wrote!) where the opposite
decision was made because it places things that are logically close very far apart.

Yes, both standard library does this quite often with _impl classes and
boost does the detail thing. To an extent I think this is window dressing; the code still is included
and the slow compile times still arise, so it's very much bending over backwards for users
of the libraries that don't like reading code.

My own view is that this is misguided in scientific code; we are all scientists and are supposed
to know how the code works, verify that it works, and sign papers staking our reputation that
it works. Hiding the code is simply encouraging abdication of that scientific responsibility. MORE people
should read the code, not less. Reading the code should be a pleasure; both more accurate and
more pleasant than reading documentation because the code is so well written.

Regarding .cc vs. .h; Of course, you can also "make install" and read the interface presented
in the install directory, which fundamentally is similar to reading under /usr/include/.

We don't actually know how the C++ standard library is laid out when it is built, only what it
looks like post install.

[mspraggs]

Absolutely. If the source/header are together it is much less painful from a development POV. I've adopted this layout in some of my own code for this very reason. And you're right, if the user runs make install then all the source files get left behind anyway.

Obviously there's no hard and fast rule, just whatever works best.

[coppolachan]

Our policy with IroIro is what I was suggesting.
We have the main headers, in an include directory. The define the basic classes or include other headers.
The headers with an associated .cpp file are all in the same directory as the source .cpp.
See here
http://suchix.kek.jp/guido_cossu/documents/DoxyGen/html/files.html

This is more or less what mspraggs was suggesting.
This is in the spirit of releasing the code as a standalone library with a clear top level organization that the final user can start looking at when reading the code.

So my original suggestion is not to move all .h but only the ones in /lib/ that are more general and clearly not associated to .cc files.
But it is a matter of taste, I know.

[coppolachan]

also another (very) minor thing would be to use the hpp naming convention for the headers so the editing tools will automatically recognize them as c++ files.

[paboyle]

I'm thinking about renaming the "lib" tree to be "Grid" and living with the annoying proliferation (*)
of "Grid" subdirectory nestings, so that the includes are all under a "Grid" directory both
before and after install.

(*)
mkdir Grid
cd Grid
git clone http://www.github.com/paboyle/Grid.git
cd ..
ls Grid/Grid/Grid/Init.cc

[coppolachan]

not a big fan of this solution, still the major include files (the ones that are in the root of lib/ now) should be in an Grid/include and not in Grid/lib.
There are only 3 .cc files related to these includes and all can be located in a lib/tools or lib/main (or better names). Not a nightmare for a developer to spot.

[paboyle]

I sym linked lib to include/Grid
All install to a subdir of include under Grid/Grid.h
Grid/Stencil.h etc...
following the directory structure under lib/