title: C++ Header files - put them in one directory or merged in a tree structure?
body: <p>I have a substantial body of source code (<a href="http://www.oofile.com.au/databasedev.html" rel="nofollow noreferrer">OOFILE</a>) which I'm <em>finally</em> putting up on <a href="http://sourceforge.net/projects/oofile/" rel="nofollow noreferrer">Sourceforge</a>. I need to decide if I should go with a monolithic include directory or keep the header files with the source tree. </p>
  
  <p>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.</p>
  
  <p>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 <a href="http://www.artima.com/forums/flat.jsp?forum=106&amp;thread=158259" rel="nofollow noreferrer">ObjectMaster</a>, 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 <a href="http://www.oofile.com.au/oofile_ref/htmlwin/annotated.html" rel="nofollow noreferrer">class list</a>, there are about 600 classes.</p>
  
  <p>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 <em>include trees</em> rather than flat <em>include dirs</em>, headers were kept with the source.</p>
  
  <p>Later, mainly to keep some Visual Studio users happy, a build was reorganised with a single <em>include</em> directory. I'm trying to choose between those models.</p>
  
  <p>The entire OOFILE product covers quite a few domains:</p>
  
  <ul>
  <li>database front-end</li>
  <li>range of database backends</li>
  <li>simple 2D graphing engine for Mac and Windows</li>
  <li>simple character-mode report-writer for trivial html and text listing</li>
  <li>very rich banding report-writer with Mac and Windows Preview and Printing and cross-platform generation of text, RTF, HTML and XML reports</li>
  <li>forms integration engine for easy CRUD forms binding to the database, with implementations on PowerPlant and MFC</li>
  <li>cross-platform utility classes
  
  <ul>
  <li>file and directory manipulation</li>
  <li>strings</li>
  <li>arrays</li>
  <li>XML and tag generation</li>
  </ul></li>
  </ul>
  
  <p>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.</p>
  
  <p>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.</p>
  
  <p>In summary, the choices seem to be:</p>
  
  <ol>
  <li>Keep original model, all headers adjacent to source - max flexibility at cost of some complex includes in projects.</li>
  <li>one include directory with everything inside</li>
  <li>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.</li>
  </ol>
  
  <p>From a Unix build aspect, the <a href="https://stackoverflow.com/questions/598167/header-files-in-multiple-directories-best-practices">recommended structure</a> has been 2. My situation is complicated by needing to keep Visual Studio and XCode users happy (sniff, CodeWarrior, how I doth miss thee!).</p>
  
  <p><strong>Edit - the chosen solution:</strong></p>
  
  <p>I went with <a href="http://oofile.svn.sourceforge.net/viewvc/oofile/trunk/include/" rel="nofollow noreferrer">four subdirectories</a> in include. I started trying to divide them up further by platform but it just got very noisy very quickly.</p>