This repo uses a modified Pitchfork Layout (PFL) convention for the project layout. See especially the README link to the project layout conventions and the 2018 blog post.
The modifications to the Pitchfork standard allow the user to have some preference for directory names. The underlying file structure follows PFL. Italicized entries are the names chosen for this repo.
Pitchfork | Alternatives |
---|---|
build | _build, bld |
tests | test, testing |
examples | example, samples |
external | extern, third-party, deps, dependencies, exogenous |
data | res, resources, dat |
tools | scripts |
docs | doc, documentation |
src | source |
include | inc |
libs | library, units, trees, components, sections, parts, modules, subdivisions, mods, subdiv, lib, src-tree, src-trees |
extras | extra, optional |
Each submodule under libs/
or extras/
can contain again the emboldened entries. (Here, I have also modified PFL to allow tools/
to be included in a submodule.)
Contents from the Pitchfork standard.
A special directory that should not be considered part of the source of the project. Used for storing ephemeral build results. must not be checked into source control. If using source control, must be ignored using source control ignore-lists.
This directory is not required, but its name should be reserved.
The build/
directory is special in that it must not be committed to a source control system. A user downloading the codebase should not see a build/
directory present in the project root, but one may be created in the course of working with the software. The _build/
directory is also reserved.
Note: Some build systems may commandeer the
build/
directory for themselves. In this case, the directory_build/
should be used in place ofbuild/
.
The build/
directory may be used for ephemeral build results. Other uses of the directory are not permitted.
Creation of additional directories for build results in the root directory is not permitted.
Note: Although multiple root directories are not allowed, the structure and layout of the
build/
directory is not prescribed. Multiple subdirectories ofbuild/
may be used to hold multiple build results of different configuration.
Contents from the Pitchfork standard.
Main compilable source location. must be present for projects with compiled components that do not use submodules.
In the presence of include/, also contains private headers.
Note: The
src/
and include/ directories are very closely related. Be sure to also read its section in addition to this one.
The purpose and content of src/
depends on whether the project authors choose to follow § 3.1.2 Merged Header Placement or § 3.1.1 Separate Header Placement.
See § 3 Library Source Layout.
Contents from the Pitchfork standard.
Directory for public headers. may be present. may be omitted for projects that do not distinguish between private/public headers. may be omitted for projects that use submodules.
Note: The
include/
and src/ directories are very closely related. Be sure to also read its section in addition to this one.
The purpose of the include/
directory is to hold public API headers.
The include/
directory should not be used if using § 3.1.2 Merged Header Placement.