Contents

1 Abstract

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

2 Background

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.

The canonical structure is primarily meant for a package – 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 end-products 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.

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.

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.

3 Introduction

The overall filesystem layout of a canonical project is presented below.

<name>/
├── <name>/
│   └── ...
└── tests/
    └── ...

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

• Header and source files (or module interface and implementation files) are next to each other (no include/ and src/ split).
• Headers are included with <> and contain the project directory prefix, for example, <libhello/hello.hpp>.
• Header and source file extensions are .hpp/.cpp (.mpp for module interfaces).
• No special characters other than _ and - in file names with . only used for extensions.

As an example, the layout of a simple libhello library could look like this:

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

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 lib prefix, for example, libhello and hello. Using the lib prefix for non-library projects should be avoided.

4 Source Directory

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

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 README, LICENSE) and directories (like doc/, tests/, examples/).

All headers within a project should be included using the <> style inclusion and contain the project name as a directory prefix. And all headers means all headers – public, private, or implementation detail, in executables or in libraries.

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

// #include "utility.hpp"           // Wrong.
// #include <utility.hpp>           // Wrong.
// #include "../hello/utility.hpp"  // Wrong.

#include <hello/utility.hpp>

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

#include <libhello/hello.hpp>

import hello.utility;

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: public header inclusions must use the library name as a directory prefix.

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 <libhello/core/hello.hpp>. When the project's headers are installed, this subdirectory hierarchy should be preserved.

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

libhello/
└── libhello/
    ├── details/
    │   └── utility.hpp
    └── ...

If a project belongs to a family of libraries 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 libstud-path and libstud-url libraries that belong to the same libstud family. Their source subdirectory layouts could look like this:

libstud-path/
└── libstud/
    └── path/
        ├── path.hpp
        ├── path-io.hpp
        └── ...

libstud-url/
└── libstud/
    └── url/
        ├── url.hpp
        ├── url-io.hpp
        └── ...

With the header inclusion paths adjusted accordingly:

#include <libstud/path/path.hpp>
#include <libstud/url/url.hpp>

5 Source Naming

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

SmallVector.hpp
small-vector.hpp
small_vector.hpp
small-vector.test.cpp

Examples of bad names:

small+vector.hpp
small.vector.hpp

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

file        .?pp

header      .hpp
module      .mpp
inline      .ipp
template    .tpp
source      .cpp

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 .?pp files with the same name are assumed to be related and are collectively called a module. This term is meant to correspond directly to a C++ module.

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, . (dot) should be replaced with either _ (underscore), - (minus), a case change, or a directory separator, according to the project's file naming scheme. For example, if libhello had two modules, hello.core and hello.extra, then their interface units could be named as follows:

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

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).

6 Source Contents

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 lib prefix for libraries), for example LIBHELLO_VERSION. Similarly, the library's namespace and module names (both public and implementation detail) should all start with the library name but without the lib prefix. For example:

// libhello/hello.mpp

export module hello.core;

namespace hello
{
  ...
}

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). A library may also have private modules in which case they shouldn't be qualified either.

// hello/hello.cpp

#include <hello/utility.hpp>
#include <libhello/utility.hpp>

namespace hello
{
  // Contains names from both utilities.
}

7 Tests

A project may have unit and/or functional/integration 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.

7.1 Unit Tests

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 .test second-level extension. For example:

libhello/
└── libhello/
    ├── hello.hpp
    ├── hello.cpp
    └── hello.test.cpp

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

Each unit test source file should implement a standalone executable (that is, define main()). 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.

7.2 Functional/Integration Tests

A project's functional/integration tests should go into the tests/ 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 tests/ could have the following layout:

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

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.

8 Acknowledgments

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