title: Embedded C file structure suggestions
body: <p>I cannot find good suggestions about file structures in typical embedded software in C. There are a number of such questions and answers here on SO, but none that covers the concerns I present, or that seems adapted to embedded systems in C.</p>
  
  <p>I understand that there is no silver bullet. If that helps narrow suggestions, my typical application must fit on targets with between 8 to 32 kB flash, and a few kB RAM. Clocks in the 4 to 20 MHz range.</p>
  
  <hr>
  
  <h2>1. Layers</h2>
  
  <p>I have seen source code organized in layers, each layer having its own directory:</p>
  
  <ul>
  <li>application</li>
  <li>transport layer</li>
  <li>hardware abstraction layer</li>
  </ul>
  
  <p>The problem is that modules often have files in all of these layers, so separating layers in directories means that the files of a single module are scattered all over the place. Poor encapsulation.</p>
  
  <hr>
  
  <h2>2. Modules in directories, h files in $ROOT/includes/</h2>
  
  <p>One directory per module. The good thing is real encapsulation. What I am not sure how to do well is how to publish the API of a module. Open source PC application SW seems to:</p>
  
  <ul>
  <li>have all source code in the module directory (all C files and all header files that are meant to be used within the module only)</li>
  <li>publish the API header file outside the module directory, into <code>$PROJ_ROOT/includes</code>.</li>
  </ul>
  
  <p>That way I can have <code>-I$PROJ_ROOT/includes</code> (or equivalent) in my compiler command, and no search paths in my <code>#include</code> statements.</p>
  
  <p>A problem is that the API is outside the module directory, thus breaking the encapsulation. It is harder to maintain a module as stand-alone in a VCS, for example.</p>
  
  <hr>
  
  <h2>3. Modules with API in directories</h2>
  
  <p>Same as above, but with the API header file in the module directory. Proper encapsulation and easier to version control modules, but the API header file is on the same level as the other module header files, which were meant to be private. The temptation to include such a "private" header file outside the module may be too great to a future developer, and it's not visible which h file was meant to be public and which weren't.</p>
  
  <hr>
  
  <h2>4. Modules with API in directories, private structure in sub-dir</h2>
  
  <p>Put only the API header file directly in the module directory, and all other files in a sub-directory or several. This could work, but I feel that the structure is growing more and more complex, which I don't really like.</p>
  
  <hr>
  
  <p>I feel that I should go for 2 or 4, but would appreciate insight greatly. How to address the related drawbacks I describe? Other alternatives? </p>
  
  <p>Links to successful open source SW of this kind of size could be nice as well. Literature advice is also welcome.</p>