The perfect project directory

This is (my) perfect directory for embedded C projects. It is loosely base on The Pitchfork Layout (PFL) which is a convention for laying out source, build, and resource files widely accepted by the C/C++ community. It is designed to provide a clear and organized structure for the project, making it easier to maintain and debug.

Top-level directories

The original PFL describes 11 top-level directories. Depending on the simplicity of the project, you can consider some of them non-essential like data/ or examples/. So feel free to skip them depending on your needs. I've added bin/ which contains the binary files for a specific architecture.

bin/
build/
src/
external/
docs/
tools/
tests/
data/
examples/
extras/

Merged header placement

The PFL structure originally defines a include/ folder to to hold all the public API headers. However I prefer to keep the source and header files in the same directory for ease of navigation.

Example:

<root>/
├─ src/
   └─ cat/
      └─ sounds/
         ├─ hiss.h
         └─ hiss.c

Essential Folders

bin/

Holds executable scripts and binaries that are run in order to use the project. These files are typically compiled from the source code in the src folder, or from third-party libraries in the external folder.

build/

Contains generated files that are produced when running build scripts. These files are compiled from the source code and can be used to create a final product. Here you can also place the project abd workspace files associated to your IDE. Example: .eww and .ewp for IAR Embedded Workbench or .ioc and .mxproject for STM32CubeIDE.

src/

Holds all the source code for the project including the main program and any modules or components. It is typically organized into sub-folders.

Optional folders

external/

Stores third-party libraries that are used in the project. Each library should occupy a single subdirectory of external/.

Subdirectories of external/ should not be modified as part of regular project development. Subdirectories should remain as close to their upstream source as possible.

Example: HAL libraries provided by the silicon vendor, and RTOS.

docs/

Contains documentation for the project and explains how the project works and how to use it.

tools/

The tools folder holds scripts and other tools that are used in the project and are useful for automating certain tasks.

tests/

Holds the test sources that are used to ensure that the project is functioning correctly. You should provide a way to disable the compilation and running of tests, especially for the purpose of embedding.

data/

It is designated for holding project files which should be included in revision control, but are not explicitly code.

Example: graphics and localization files are not code in the same sense as the rest of the project, but are good candidates for inclusion in the data/ directory.

examples/

It is reserved for source files related to example and sample usage of the project that can be used as a point of reference for developers.

extras/

Finally, the extras folder contains any miscellaneous files related to the project.