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 │ ├── design.md │ ├── mainpage.h ├── scripts ├── DEPENDENCIES ├── LICENSE └── README.md
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.
|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 design.md, 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.|
Certain files should be found in every repository, those files are described below.
|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
|doc/mainpage.h||Introductory component documentation.|
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.
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.