C++ Header files - put them in one directory or merged in a tree structure?

Question

I have a substantial body of source code (OOFILE) which I'm finally putting up on Sourceforge. I need to decide if I should go with a monolithic include directory or keep the header files with the source tree.

I want to make this decision before pushing to the svn repo on SourceForge. I expect a lot of people who use it after that move will keep a working copy checked out directly from SF so won't want to change their structure.

The full source tree has about 262 files in 25 folders. There are a lot more classes than that suggests as due to conforming to 8.3 character names (yes it dates back to Win3.1) many classes are in one file. As I used to develop with ObjectMaster, that never bothered me but I will be splitting it up to conform to more recent trends to minimise the number of classes per file. From a quick skim of the class list, there are about 600 classes.

OOFILE is a cross-platform product expected to be built on Mac, Windows and assorted Unix platforms. As it started life on Mac, with compilers that point to include trees rather than flat include dirs, headers were kept with the source.

Later, mainly to keep some Visual Studio users happy, a build was reorganised with a single include directory. I'm trying to choose between those models.

The entire OOFILE product covers quite a few domains:

• database front-end
• range of database backends
• simple 2D graphing engine for Mac and Windows
• simple character-mode report-writer for trivial html and text listing
• very rich banding report-writer with Mac and Windows Preview and Printing and cross-platform generation of text, RTF, HTML and XML reports
• forms integration engine for easy CRUD forms binding to the database, with implementations on PowerPlant and MFC
• cross-platform utility classes
  • file and directory manipulation
  • strings
  • arrays
  • XML and tag generation

Many people only want to use it on a single platform and some of those code areas are pure legacy (eg: PowerPlant UI framework on classic Mac). It therefore seems people would appreciate not having headers from those unwanted areas dumped in their monolithic include directory.

I started thinking about having an include directory split up into a few of the domains above and then realised that was sounding more like the original structure.

In summary, the choices seem to be:

1. Keep original model, all headers adjacent to source - max flexibility at cost of some complex includes in projects.
2. one include directory with everything inside
3. split includes by domain, so there may be about 6 directories for someone using the lot but a pure database user would probably have a single directory.

From a Unix build aspect, the recommended structure has been 2. My situation is complicated by needing to keep Visual Studio and XCode users happy (sniff, CodeWarrior, how I doth miss thee!).

Edit - the chosen solution:

I went with four subdirectories in include. I started trying to divide them up further by platform but it just got very noisy very quickly.

Answer 1

Personally I would go with 2, or 3 if really pushed.

But whichever you choose, please make it crystal clear in the build instructions how to set up the include paths. Nothing dooms an open source project more than it being really difficult to build - developers want a quick out-of-the-box experience and if it involves faffing around with many undocumented environment variables (or whatever) most will simply go away.