Source code repository directory structure

In order to make it easier to navigate through new repositories they should follow a common directory structure. The tree structure below shows a repository with two components sharing a ‘doc’ directory and ‘component-test’ directory. Many repos will likely contain only one component, in which case the structure should be the same but with only one sub-directory with the source code etc.

├── cmake_modules
├── component-A
│   ├── include
│   ├── src
│   ├── unit-test
│   │   ├── test-data
├── component-B
│   ├── include
│   ├── src
│   ├── unit-test
│   │   ├── test-data
├── component-test
│   ├── test-data
├── doc
│   ├── images
│   │   └── *.png
│   ├──
│   ├── mainpage.h
├── scripts

The table below describes the directories and their purpose. The <component-subdir> represents e.g. the ‘component-A’ or ‘component-B’ directories in the tree structure above. Some directories are only relevant in some situations, e.g. a ‘test-data’ dir is only relevant if there is any actual test data of course.

Directory Description
scripts Contains e.g. utility scripts that might be needed to e.g. set up an environment or such like.
cmake_modules Contains any CMake ‘find’ modules.
doc Contains Doxygen files for generating reference documentation that is not part of any class etc, e.g. introductory pages and topic overviews. Contains, describing the design of the component in an arc42 structure.
doc/images Contains images for the design and Doxygen documentation. The preferred file format is png. If the image is generated from another document, it is recommended to keep that document here as well, e.g. a UML model.
component-test Contains tests and any stubs used in component tests.
component-test/test-data Contains any test data that the component tests uses.
<component-subdir>/include Contains any public header files, those that would typically be installed in a development package.
<component-subdir>/src Contains source and private header files.
<component-subdir>/unit-test Contains unit tests and any stubs used in unit tests.
<component-subdir>/unit-test/test-data Contains any test data that the unit tests uses.

Mandatory files

Certain files should be found in every repository, those files are described below.

File Description
README(.md) A top-level README giving a brief introduction to the repository. How to build, how to run tests, other “good to know” information. The .md suffix for markdown syntax may be used.
LICENSE The source code and project license.
DEPENDENCIES Describes any non-trivial dependency used by a component. Typically a library linked against such as libfoo would be listed while a compiler and libstdc++ would not be listed.
For OSS projects this file should exist and contain the following information:
  • How and where to file bug reports and what information is expected in them.
  • How the development flow works, for instance forks and merge requests.
  • Brief about code standard
doc/mainpage.h Introductory component documentation.

Directory naming

All directories should be lower case only, and using “-” as a separator between words. No other symbols other than [a..z], [0..9] and “-” are allowed. Exceptions are allowed if there is a technical need which is cumbersome to work around.

File naming

The source code and header files should be named using lower case letters only, without any word separator. No other symbols other than [a..z] and [0..9] are allowed. C++ source files should be suffixed “.cpp” and header files “.h”. The exception is test code files where an underscore is used to separate the name of what is tested and a suffix showing that it is a test, e.g. a unit with the name ‘mymodule.cpp’/’mymodule.h’ would have a corresponding unit test implemented in a file named ‘mymodule_unittest.cpp’.


The repository meta data files such as the README, license and Makefiles are allowed to use upper case letters in their naming.