<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <meta charset="UTF-8"/>
  <meta name="viewport" content="width=device-width, initial-scale=1"/>
  <meta name="title" content="Canonical Project Structure"/>

  <title>Canonical Project Structure</title>

  <style type="text/css">

html
{
  font-family: "Helvetica Neue", Helvetica, "Segoe UI", Arial, freesans, sans-serif;
  font-weight: normal;
  font-size: 18px;
  line-height: 1.4em;
  letter-spacing: 0.01em;

  color: #292929;
}

body {margin: 0;} /* There is non-0 default margin for body. */

/* See notes on what's going on here. */
body {min-width: 17em;}
@media only screen and (min-width: 360px)
{
  body {min-width: 19em;}
}

/*
 * Header (optional).
 */

#header-bar
{
  width: 100%;

  background: rgba(0, 0, 0, 0.04);
  border-bottom: 1px solid rgba(0, 0, 0, 0.2);

  padding: .4em 0 .42em 0;
  margin: 0 0 1.4em 0;
}

#header
{
  /* Same as in #content. */
  max-width: 41em;
  margin: 0 auto 0 auto;
  padding: 0 .4em 0 .4em;

  -webkit-box-sizing: border-box;
  -moz-box-sizing: border-box;
  box-sizing: border-box;

  width: 100%;
  display: table;
  border: none;
  border-collapse: collapse;
}

#header-logo, #header-menu
{
  display: table-cell;
  border: none;
  padding: 0;
  vertical-align: middle;
}

#header-logo {text-align: left;}
#header-menu {text-align: right;}

/* These overlap with #header's margin because of border collapsing. */
#header-logo {padding-left: .4em;}
#header-menu {padding-right: .4em;}

#header-logo a
{
  color: #000;
  text-decoration: none;
  outline: none;
}
#header-logo a:visited {color: #000;}
#header-logo a:hover, #header-logo a:active {color: #000;}

#header-menu a
{
  font-size: 0.889em;
  line-height: 1.4em;
  text-align: right;
  margin-left: 1.2em;
  white-space: nowrap;
  letter-spacing: 0;
}

#header-menu a
{
  color: #000;
  outline: none;
}
#header-menu a:visited {color: #000;}
#header-menu a:hover, #header-menu a:active
{
  color: #3870c0;
  text-decoration: none;
}

/* Flexbox-based improvements though the above works reasonably well. */
#header-menu-body
{
  width: 100%;

  display: -webkit-inline-flex;
  display: inline-flex;

  -webkit-flex-flow: row wrap;
  flex-flow: row wrap;

  -webkit-justify-content: flex-end;
  justify-content: flex-end;
}

/* Whether we want it (and at which point) depends on the size of the menu. */
/*
@media only screen and (max-width: 567px)
{
  #header-menu-body
  {
    -webkit-flex-direction: column;
    flex-direction: column;
  }
}
*/

/*
 * Content.
 */

#content
{
  max-width: 41em;
  margin: 0 auto 0 auto;
  padding: 0 .4em 0 .4em; /* Space between text and browser frame. */

  -webkit-box-sizing: border-box;
  -moz-box-sizing: border-box;
  box-sizing: border-box;
}

/*
 * Footer (optional).
 */

#footer
{
  color: #767676;
  font-size: 0.7223em;
  line-height: 1.3em;
  margin: 2.2em 0 1em 0;
  text-align: center;
}

#footer a
{
  color: #767676;
  text-decoration: underline;
}
#footer a:visited {color: #767676;}
#footer a:hover, #footer a:active {color: #3870c0;}

/* Screen size indicator in the footer. The before/after content is in case
   we don't have any content in the footer. Margin is to actually see the
   border separate from the browser frame. */

/*
#footer:before {content: "\A0";}
#footer:after {content: "\A0";}

#footer
{
  border-left: 1px solid;
  border-right: 1px solid;
  margin-left: 1px;
  margin-right: 1px;
}

@media only screen and (max-width: 359px)
{
  #footer {border-color: red;}
}

@media only screen and (min-width: 360px) and (max-width: 567px)
{
  #footer {border-color: orange;}
}

@media only screen and (min-width: 568px) and (max-width: 1023px)
{
  #footer {border-color: blue;}
}

@media only screen and (min-width: 1024px)
{
  #footer {border-color: green;}
}
*/

/*
 * Common elements.
 */

p, li, dd {text-align: justify;}
.code {text-align: left;} /* Manually aligned. */
pre {text-align: left;}   /* If it is inside li/dd. */

/* Notes. */

.note
{
  color: #606060;
}

div.note
{
  margin: 2em 0 2em 0; /* The same top/bottom margings as pre box. */

  padding-left: 0.5em;
  border: 0.25em;
  border-left-style: solid;
  border-color: #808080;

  page-break-inside: avoid;
}

div.note :first-child {margin-top:    0;}
div.note :last-child  {margin-bottom: 0;}

span.note::before {content: "[Note: "}
span.note::after  {content: "]"}

/* Links. */
a
{
  color: #3870c0;
  /*color: #4078c0;*/
  text-decoration: none;
}

a:hover, a:active
{
/*color: #006fbf;*/
/*color: #0087e7;*/
  text-decoration: underline;
}

a:visited
{
/*color: #003388;*/
  color: #00409c;
}

/* Standard lists. */
ul, ol, dl {margin: 1em 0 1em 0;}
ul li, ol li {margin: 0 0 .4em 0;}
ul li {list-style-type: circle;}
dl dt {margin: 0 0 0 0;}
dl dd {margin: 0 0 .6em 1.8em;}

code, pre
{
  font-family: Consolas, "Liberation Mono", Menlo, Courier, monospace;
  font-size: 0.92em;
  letter-spacing: 0;
}

pre {white-space: pre-wrap;}

@media only screen and (max-width: 567px)
{
  pre {word-break: break-all;}
}

/* Use page rather than system font settings. */
input
{
  font-family: inherit;
  font-weight: inherit;
  font-size:   inherit;
  line-height: inherit;
}

pre
{
  background-color: rgba(0, 0, 0, 0.05);
  border-radius: 0.2em;
  padding: .8em .4em .8em .4em;
  margin: 2em -.4em 2em -.4em; /* Use margins of #content. */
}

code
{
  background-color: rgba(0, 0, 0, 0.05);
  border-radius: 0.2em;
  padding: .2em .32em .18em .32em;
}

/*
code::before
{
  letter-spacing: -0.2em;
  content: "\00a0";
}

code::after
{
  letter-spacing: -0.2em;
  content: "\00a0";
}
*/

/* Bases:
 *
 * common.css
 * pre-box.css
 * code-box.css
 *
 */

#content
{
  max-width: 43.6em;
  padding-left: 3em; /* Reserve for headings. */
}

h1
{
  font-weight: normal;
  font-size: 2em;
  line-height: 1.4em;
  margin: 1.6em 0 .6em -1.4em;
}

h1.preface
{
  margin-left: -.56em;
}

h2
{
  font-weight: normal;
  font-size: 1.556em;
  line-height: 1.4em;
  margin: 1.6em 0 .6em -.8em;
}

h3
{
  font-weight: normal;
  font-size: 1.3em;
  line-height: 1.4em;
  margin: 1.6em 0 .6em -.2em;
}

/* Title page */

#titlepage {
  margin: 0 0 4em 0;
  border-bottom: 1px solid black;
}

#titlepage .title {
  font-weight: normal;
  font-size: 2.333em;
  line-height: 1.4em;
  letter-spacing: 0;
  text-align: center;
  margin: 2em 0 2em 0;
}

#titlepage p {
  font-size: 0.889em;
  line-height: 1.4em;
  margin: 2em 0 .6em 0;
}

table.toc
{
  border-style      : none;
  border-collapse   : separate;
  border-spacing    : 0;

  margin            : 0.2em 0 0.2em 0;
  padding           : 0 0 0 0;
}

table.toc tr
{
  padding           : 0 0 0 0;
  margin            : 0 0 0 0;
}

table.toc * td, table.toc * th {
  border-style      : none;
  margin            : 0 0 0 0;
  vertical-align    : top;
}

table.toc * th
{
  font-weight       : normal;
  padding           : 0 0.8em 0 0;
  text-align        : left;
  white-space       : nowrap;
}

table.toc * table.toc th
{
  padding-left      : 1em;
}

table.toc * td
{
  padding           : 0 0 0 0;
  text-align        : left;
}

table.toc * td.preface
{
  padding-left      : 1.35em;
}


#titlepage .title
{
  font-size: 2em;
}

/*
 * Property list table.
 */
.proplist
{
  width: calc(100%); /* Fill the page. */

  table-layout: fixed;

  border: none;
  border-spacing: 0 0;
}

.proplist th, .proplist td {padding: .1em 0 .1em 0;}

.proplist th
{
  font-weight: normal;
  text-align: left;

  width: 7em;
}
.proplist th:after {content: ":";}
  </style>

</head>
<body>
<div id="content">

  <div id="titlepage">
    <div class="title">Canonical Project Structure</div>

    <table class="proplist">
      <tbody>
	<tr><th>Document</th><td><a href="https://wg21.link/P1204R0">P1204R0</a></td></tr>
	<tr><th>Audience</th><td>SG15</td></tr>
	<tr><th>Authors</th><td>Boris Kolpackov (Code Synthesis)</td></tr>
	<tr><th>Reply-To</th><td>boris@codesynthesis.com</td></tr>
	<tr><th>Date</th><td>2018-10-08</td></tr>
      </tbody>
    </table>
  </div>
  <h2 id="toc">Contents</h2>

  <table class="toc">
    <tr><th>1</th><td><a href="#abstract">Abstract</a></td></tr>
    <tr><th>2</th><td><a href="#background">Background</a></td></tr>
    <tr><th>3</th><td><a href="#intro">Introduction</a></td></tr>
    <tr><th>4</th><td><a href="#src-dir">Source Directory</a></td></tr>
    <tr><th>5</th><td><a href="#src-name">Source Naming</a></td></tr>
    <tr><th>6</th><td><a href="#src-content">Source Contents</a></td></tr>
    <tr><th>7</th><td><a href="#tests">Tests</a>
      <table class="toc">
        <tr><th>7.1</th><td><a href="#tests-unit">Unit Tests</a></td></tr>
        <tr><th>7.2</th><td><a
href="#tests-integration">Functional/Integration Tests</a></td></tr>
      </table>
    </td></tr>
    <tr><th>8</th><td><a href="#ack">Acknowledgments</a></td></tr>
  </table>

  <h2 id="abstract">1 Abstract</h2>

  <p><i>We would like to propose source code layout and content guidelines for
  new C++ projects that would facilitate their packaging.</i></p>

  <h2 id="background">2 Background</h2>

  <p>The goal of establishing a canonical C++ project structure is to create
  an ecosystem of C++ packages that can coexist, are easy to comprehend by
  both humans and tools, scale to complex, real-world requirements, and, last
  but not least, are pleasant to work with.</p>

  <p>The canonical structure is primarily meant for a <i>package</i> &#8211; a
  single library or program (or, sometimes, a collection of related programs)
  with a specific and well-defined function. While it may be less suitable for
  more elaborate, multi-library/program <i>end-products</i> that are not meant
  to be packaged, most of the recommendations discussed below would still
  apply. Specifically, we often find ourselves factoring common functionality
  out of such end-products and into separate packages, for example, in order
  to reuse it in other end-products. In this light, it may make sense to start
  a new end-product project as a composition of individual packages that
  follow the canonical structure.</p>

  <p>Note also that these guidelines are intentionally minimal. They are only
  meant to cover the parts necessary to build a C++ project from source code
  and then validate the result (run tests). Specifically, we omit topics such
  as binary packages, examples, documentation, etc.</p>

  <p>We also do not concern ourselves with actual packaging and dependency
  management. Rather, the goal is to make it easy for a project that follows
  the canonical structure to be built with any modern build system and
  packaged for any modern dependency manager. Specifically, we are not trying
  to describe a layout that could be handled fully automatically assuming that
  support for a new build system/dependency manager will still likely have to
  be added manually. However, the layout should be "sane enough" to make this
  task straightforward.</p>

  <h2 id="intro">3 Introduction</h2>

  <p>The overall filesystem layout of a canonical project is presented
  below.</p>

  <pre>&lt;name>/
├── &lt;name>/
│   └── ...
└── tests/
    └── ...</pre>

  <p>This layout and its semantics are discussed in detail in the following
  sections with a short summary of the key points presented next.</p>

  <ul>
  <li style="margin-top:2em"><i>Header and source files (or module interface
  and implementation files) are next to each other (no <code>include/</code>
  and <code>src/</code> split).</i></li>

  <li style="margin-top:1em"><i>Headers are included with <code>&lt;></code>
  and contain the project directory prefix, for example,
  <code>&lt;libhello/hello.hpp></code>.</i></li>

  <li style="margin-top:1em"><i>Header and source file extensions are
  <code>.hpp/.cpp</code> (<code>.mpp</code> for module interfaces).</i></li>

  <li style="margin-top:1em;margin-bottom:2em"><i>No special characters other
  than <code>_</code> and <code>-</code> in file names with <code>.</code>
  only used for extensions.</i></li>
  </ul>

  <p>As an example, the layout of a simple <code>libhello</code> library could
  look like this:</p>

  <pre>libhello/
├── libhello/
│   ├── hello.hpp
│   ├── hello.cpp
│   └── hello.test.cpp
└── tests/
    └── basics/
        └── driver.cpp</pre>

  <p>If a project consists of a library and an executable, then they should be
  split into separate projects. In this case, by convention, the library name
  should start with the <code>lib</code> prefix, for example,
  <code>libhello</code> and <code>hello</code>. Using the <code>lib</code>
  prefix for non-library projects should be avoided.</p>

  <div class="note">
  <p>An initial draft of these guidelines made the <code>lib</code> prefix for
  libraries a requirement. This, however, encountered strong push-back from
  early reviewers. Based on this feedback as well as to help with the adoption
  of these guidelines by existing projects, the <code>lib</code> prefix has
  been made optional.</p>

  <p>However, it is still strongly recommended to follow this convention in
  new projects since it offers several benefits:</p>

  <ol>
  <li style="margin-top:1em">It is clear from the name to both humans and
  tools what kind of project it is.</li>

  <li style="margin-top:1em">All libraries are consistently named (as opposed
  to some with the <code>lib</code> prefix and some without).</li>

  <li style="margin-top:1em">All library names are future-proofed to co-exist
  with executables. If one starts with a library without the <code>lib</code>
  prefix but later decides to add an executable, renaming the library would
  unlikely be an option. And there is no need to spend mental energy on
  thinking whether it's possible that an executable will be added later.</li>
  </ol>
  </div>

  <h2 id="src-dir">4 Source Directory</h2>

  <p>The project's source code is placed into a subdirectory of the root
  directory named the same as the project, for example,
  <code>hello/hello/</code> or <code>libhello/libhello/</code>. It is called
  the project's <i>source subdirectory</i>.</p>

  <p>There are several reasons for this layout: It implements the canonical
  inclusion scheme (discussed below) where each header is prefixed with its
  project name. It also has a predictable name where users (and tools) can
  expect to find the project's source code. Finally, this layout prevents
  clutter in the project's root directory which usually contains various other
  files (like <code>README</code>, <code>LICENSE</code>) and directories (like
  <code>doc/</code>, <code>tests/</code>, <code>examples/</code>).</p>

  <div class="note">
  <p>Another popular approach is to place public headers into the
  <code>include/</code> subdirectory and source files as well as private
  headers into <code>src/</code>. The cited advantage of this layout is the
  predictable location (<code>include/</code>) that contains only the
  project's public headers (that is, its API). This can make the project
  easier to navigate and understand while harder to misuse, for example, by
  including a private header.</p>

  <p>However, this split layout is not without drawbacks:</p>

  <ul>
  <li>Navigating between corresponding headers and sources is cumbersome. This
  affects editing, grep'ing, as well as code browsing (for example, on
  GitHub).</li>

  <li>Implementing the canonical inclusion scheme would require an extra level
  of subdirectories (for example, <code>include/libhello/</code> and
  <code>src/libhello/</code>), which only amplifies the previous issue.</li>

  <li>Supporting generated source code can be challenging: Source code
  generators rarely provide support for writing headers and sources into
  different directories. Even if we can move things around post-generation,
  many build systems do not easily support this arrangement.</li>
  </ul>

  <p>Also, the stated advantage of this layout &#8211; separation of public
  headers from private &#8211; is not as clear cut as it may seem at first.
  The common assumption of the split layout is that only headers from
  <code>include/</code> are installed and, conversely, to use the headers
  in-place, all one has to do is add <code>-I</code> pointing to
  <code>include/</code>. On the other hand, it is common for public headers to
  include private, for example, to call an implementation detail function in
  inline or template code (note that the same applies to private modules
  imported in public module interfaces). Which means such private, (or,
  probably now more accurately called <i>implementation detail</i>) headers
  have to be placed in the <code>include/</code> directory as well, perhaps
  into a subdirectory (such as <code>details/</code>) or with a file name
  suffix (such as <code>-impl</code>) to signal to the user that they are
  still "private". Needless to say, in an actively developed project, keeping
  track of which private headers can still stay in <code>src/</code> and which
  have to be moved to <code>include/</code> (and vice versa) is a tedious,
  error-prone task. As a result, practically, the split layout quickly
  degrades into the "all headers in <code>include/</code>" arrangement which
  negates its main advantage.</p>

  <p>It is also not clear how the split layout will translate to modularized
  projects. With modules, both the interface and implementation (including
  non-inline/template function definitions) can reside in the same file with a
  substantial number of C++ developers finding this arrangement appealing. If
  a project consists of only such single-file modules, then
  <code>include/</code> and <code>src/</code> have effectively become the same
  thing (note that there couldn't be any "private" modules in
  <code>src/</code> since there would be nobody to import them).  In a sense,
  we already have this situation with header-only libraries except that in the
  case of modules calling the directory <code>include/</code> would be an
  anachronism.</p>

  <p>To summarize, the split directory arrangement offers little benefit over
  the single directory layout, has a number of real drawbacks, and does not
  fit modularized projects well. In practice, private headers are placed into
  <code>include/</code>, often either in a subdirectory or with a special file
  name suffix, a mechanism that is readily available in the single directory
  layout.</p>
  </div>

  <p>All headers within a project should be included using the
  <code>&lt;></code> style inclusion and contain the project name as a
  directory prefix. And all headers means <i>all headers</i> &#8211; public,
  private, or implementation detail, in executables or in libraries.</p>

  <p>As an example, let's say we've added <code>utility.hpp</code> to the
  <code>hello</code> executable project. This is how it should be included in
  <code>hello.cpp</code>:</p>

  <pre>// #include "utility.hpp"           // Wrong.
// #include &lt;utility.hpp>           // Wrong.
// #include "../hello/utility.hpp"  // Wrong.

#include &lt;hello/utility.hpp></pre>

  <p>Similarly, if we want to include <code>hello.hpp</code> from
  <code>libhello</code>, then the inclusion should look like this:</p>

  <pre>#include &lt;libhello/hello.hpp></pre>

  <div class="note">
  <p>The problem with the <code>""</code> style inclusion is if the header is
  not found relative to the including file, most implementations will continue
  looking for it in the include search paths, the same as for
  <code>&lt;></code>. As a result, if the header is not present in the right
  place (for example, because it was mistakenly not listed as to be
  installed), chances are that a completely unrelated header with the same
  name will be found and included. Needless to say, debugging situations like
  these is unpleasant.</p>

  <p>Prefixing all inclusions with the project name also makes sure that
  headers with common names (for example, <code>utility.hpp</code>) can
  coexist (for example, when installed into a system-wide directory, such as
  <code>/usr/include</code>). The prefix also plays an important role in
  supporting auto-generated headers.</p>

  <p>Note also that this header inclusion scheme is consistent with the module
  importation, for example:</p>

  <pre>import hello.utility;</pre>

  <p>Finally, note that while adding the project prefix to the <code>""</code>
  style inclusion (for example, <code>"libhello/hello.hpp"</code>) will make
  finding an unrelated header unlikely, there is still a possibility. And it
  is not clear why take the chance when there are no benefits (one such cited
  benefit is the ability to distinguish inclusions of "this project's headers"
  vs "external headers").</p>
  </div>

  <p>If you have to disregard every rule and recommendation in these
  guidelines but one, for example, because you are working on an existing
  library, then insist on this: <b>public header inclusions must use the
  library name as a directory prefix</b>.</p>

  <p>The project's source subdirectory can have subdirectories of its own, for
  example, to organize the code into components. Naturally, header inclusions
  will need to contain such subdirectories, for example
  <code>&lt;libhello/core/hello.hpp></code>. When the project's headers are
  installed, this subdirectory hierarchy should be preserved.</p>

  <p>If you need to separate public API headers/modules from implementation
  details, the convention is to place them into the <code>details/</code>
  subdirectory. For example:</p>

  <pre>libhello/
└── libhello/
    ├── details/
    │   └── utility.hpp
    └── ...</pre>

  <div class="note">
  <p>If a project has truly private headers (for example, proprietary code)
  that must be clearly separated from public and implementation detail
  headers, then they can be placed into the <code>private/</code>
  subdirectory, next to <code>details/</code>. In a sense, this arrangement
  mimics the C++ public/protected/private member access.</p>
  </div>

  <p>If a project belongs to a <i>family of libraries</i> with a common name
  prefix, then it may use a nested source directory layout with a common
  top-level directory. As an example, let's say we have the
  <code>libstud-path</code> and <code>libstud-url</code> libraries that belong
  to the same <code>libstud</code> family. Their source subdirectory layouts
  could look like this:</p>

  <pre>libstud-path/
└── libstud/
    └── path/
        ├── path.hpp
        ├── path-io.hpp
        └── ...

libstud-url/
└── libstud/
    └── url/
        ├── url.hpp
        ├── url-io.hpp
        └── ...</pre>

  <p>With the header inclusion paths adjusted accordingly:</p>

  <pre>#include &lt;libstud/path/path.hpp>
#include &lt;libstud/url/url.hpp></pre>

  <h2 id="src-name">5 Source Naming</h2>

  <p>When naming source files, only use ASCII alphabetic characters, digits,
  as well as <code>_</code> (underscore) and <code>-</code> (minus). Use
  <code>.</code> (dot) only for extensions, that is, trailing parts of the
  name that <i>classify</i> the project's files. Examples of good names:</p>

  <pre>SmallVector.hpp
small-vector.hpp
small_vector.hpp
small-vector.test.cpp</pre>

  <p>Examples of bad names:</p>

  <pre>small+vector.hpp
small.vector.hpp</pre>

  <div class="note">
  <p>If you are using <code>_</code> or <code>-</code> as word separators in
  filesystem names, pick one and use it consistently throughout the
  project.</p>
  </div>

  <p>The C source file extensions should be <code>.h</code>/<code>.c</code>
  and the C++ source file extension scheme should be <code>.?pp</code>:</p>

  <pre>file        .?pp

header      .hpp
module      .mpp
inline      .ipp
template    .tpp
source      .cpp</pre>

  <p>The use of inline and template files is optional. If used, they are
  included at the end of the header/module files and contain definitions of
  inline and non-inline template functions, respectively. The
  <code>.?pp</code> files with the same name are assumed to be related and are
  collectively called a <i>module</i>. <span class="note">This term is meant
  to correspond directly to a C++ module.</span></p>

  <div class="note">
  <p>There are several reasons not to "reuse" the <code>.h</code> C header
  extension for C++ files:</p>

  <ul>
  <li>There can be a need for both C and C++ headers for the same module.</li>

  <li>It allows tools to accurately determine the language from the file
  name.</li>

  <li>It is easier to search for C++ source code using wildcard patterns
  (<code>*.?pp</code>).</li>
  </ul>

  <p>The last two reasons are also why headers without extensions are probably
  not worth the trouble.</p>
  </div>

  <p>Source files corresponding to C++ modules need to embed a sufficient
  amount of module name suffix in their names to unambiguously resolve all the
  modules used in a project. When deriving file names from C++ module names,
  <code>.</code> (dot) should be replaced with either <code>_</code>
  (underscore), <code>-</code> (minus), a case change, or a directory
  separator, according to the project's file naming scheme. For example, if
  <code>libhello</code> had two modules, <code>hello.core</code> and
  <code>hello.extra</code>, then their interface units could be named as
  follows:</p>

  <pre>hello-core.mpp
hello-extra.mpp

hello_core.mpp
hello_extra.mpp

HelloCore.mpp
HelloExtra.mpp

hello/core.mpp
hello/extra.mpp

core.mpp
extra.mpp</pre>

  <p>As discussed in the next section, public module names should start with
  the project name and for such modules it is customary to omit this first
  component from file names (the last variant in the above example).</p>

  <div class="note">
  <p>See <a
  href="https://build2.org/build2/doc/build2-build-system-manual.xhtml#cxx-modules-build">Building
  Modules</a> in the <code>build2</code> documentation for a description of a
  module name to file name mapping algorithm that uses this naming scheme.</p>
  </div>

  <h2 id="src-content">6 Source Contents</h2>

  <p>All macros defined by a project, such as include guards, version and
  symbol export macros, etc., must all start with the project name (including
  the <code>lib</code> prefix for libraries), for example
  <code>LIBHELLO_VERSION</code>. Similarly, the library's namespace and module
  names (both public and implementation detail) should all start with the
  library name but without the <code>lib</code> prefix. For example:</p>

  <pre>// libhello/hello.mpp

export module hello.core;

namespace hello
{
  ...
}</pre>

  <p>An executable project may use a namespace (in which case it is natural to
  call it after the project) and its (private) modules shouldn't be qualified
  with the project name (in order not to clash with similarly named modules
  from the corresponding library, if any). <span class="note">A library may
  also have private modules in which case they shouldn't be qualified
  either.</span></p>

  <div class="note">
  <p>Hopefully by now the recommendation for the <code>lib</code> prefix
  should be easy to understand: oftentimes executables and libraries come in
  pairs, for example <code>hello</code> and <code>libhello</code>, with the
  reusable functionality being factored out from the executable into the
  library. It is natural to want to use the same name <i>stem</i>
  (<code>hello</code> in our case) for both.</p>

  <p>The above naming scheme (with the <code>lib</code> prefix present in some
  names but not others) is carefully chosen to allow such library/executable
  pairs to coexist and be used together without too much friction. For
  example, both the library and executable can have a header called
  <code>utility.hpp</code> with the executable being able to include both and
  even get the "merged" functionality without extra effort (since they use the
  same namespace):</p>

  <pre>// hello/hello.cpp

#include &lt;hello/utility.hpp>
#include &lt;libhello/utility.hpp>

namespace hello
{
  // Contains names from both utilities.
}</pre>
  </div>

  <h2 id="tests">7 Tests</h2>

  <p>A project may have <i>unit</i> and/or <i>functional/integration</i>
  tests. Unit tests exercise each module's (potentially private) functionality
  in isolation. In contrast, functional/integration tests exercise the project
  via its public API, just like the real users of the project would.</p>

  <h3 id="tests-unit">7.1 Unit Tests</h3>

  <p>A source file that implements a module's unit tests should be placed next
  to that module's files and be called with the module's name plus the
  <code>.test</code> second-level extension. For example:</p>

  <pre>libhello/
└── libhello/
    ├── hello.hpp
    ├── hello.cpp
    └── hello.test.cpp</pre>

  <p>All source files (that is, headers, modules, etc) with the
  <code>.test</code> second-level extension are assumed to belong to unit
  tests and should be excluded from the library/executable build.</p>

  <div class="note">
  <p>The use of a second-level extension rather than a file name suffix (for
  example, <code>hello-test.cpp</code>) has several advantages. Firstly, it is
  conceptually fitting since being a test is just another <i>axis of
  classification</i>, not unlike being a C++ source file.</p>

  <p>Also, <code>.test</code> makes things more robust at the build system
  level where files belonging to unit tests can be handled with a wildcard
  (<code>*.test.cpp</code>). In contrast, <code>*-test.cpp</code> is more
  likely to pick up something that fits the naming schema accidentally, for
  example, <code>midterm-test.cpp</code>.</p>
  </div>

  <p>Each unit test source file should implement a standalone executable (that
  is, define <code>main()</code>). It should be possible to run such an
  executable without any command line arguments or inputs in order to perform
  all the unit tests of a module. Such an executable should indicate success
  by terminating normally with the zero exit code.</p>

  <h3 id="tests-integration">7.2 Functional/Integration Tests</h3>

  <p>A project's functional/integration tests should go into the
  <code>tests/</code> subdirectory. Each such test should reside in a separate
  subdirectory, potentially organized into nested subdirectories (for
  instance, to correspond to the source directory components). For example, if
  we were creating an XML parsing and serialization library, then its
  <code>tests/</code> could have the following layout:</p>

  <pre>tests/
├── basics/
│   └── driver.cpp
├── parser/
│   ├── pull/
│   │   └── driver.cpp
│   └── push/
│       └── driver.cpp
└── serializer/
    └── ...</pre>

  <div class="note">
  <p>A reasonable question to ask is why place functional/integration tests
  into a separate subdirectory while unit tests next to the modules that they
  test. The main reason is the ability to run the former against an installed
  version of a library (if you think about it, the way most build systems do
  it currently is backwards: they first run the tests and then install the
  result, which may end up with missing headers, wrong rpaths, etc).</p>

  <p>So some build systems (such as <code>build2</code>) have a notion of
  subprojects that can be configured and built independently of their
  superproject. But to make something a subproject, it normally has to be a
  separate directory.</p>
  </div>

  <p>Each functional/integration test should result in a single executable
  that indicates success by terminating normally with the zero exit code.
  While such tests may require command line arguments, inputs, and/or, output
  analysis, to facilitate packaging, such requirements should be avoided, if
  possible.</p>

  <h2 id="ack">8 Acknowledgments</h2>

  <p>Thanks to Titus Winters, Robert Schumacher, and Joël Lamotte for
  providing valuable feedback on earlier drafts of this document.</p>

</div>

</body>
</html>
