Project layout

Every non-trivial project benefits from a bit of organization. One aspect of this is the layout of the project directory.

Z-Com follows a relatively straight-forward approach as outlined here:

.
├── .cmake-build/
├── .git/
│   └── hooks/
├── .github/
│   └── workflows/
├── cmake/
├── include/
│   └── libzcom/
├── src/
│   ├── libzcom/
│   └── zcom/
├── scripts/
├── tests/
├── tools/
├── www/
├── .clang-format
├── .clang-tidy
├── .editorconfig
├── .gitattributes
├── .gitignore
├── .gitmodules
├── CMakeLists.txt
├── CMakePresets.json
├── README.md
└── vcpkg.json

Essentially, the root folder contains configuration for all the development tools. It also contains the top level entry point for CMake, the vcpkg manifest, and last, but not least, the README file.

The .cmake-build directory is the build folder and therefore ignored by git. Of course, there is the .git folder for the VCS metadata, but the hooks folder underneath it is going to be important, because there will be some git hooks set up to ensure that clang-format and clang-tidy run before a commit gets through.

Similarly, the .github folder contains all relevant configuration for the github project, for example the workflow to build this website.

The cmake directory contains various CMake support scripts, like the LLVM for Windows toolchain, or overlayports for vcpkg.

include is used for public library headers, with subfolders for each library. In this example, there’s an imaginary libzcom for which the public headers exist in include/libzcom.

src contains sources for various components of the projects. Sticking with the libzcom example, the sources for it would be located under src/libzcom. Likewise, the zcom executable’s sources live under src/zcom.

Next up, there is a scripts directory. Scripts are used to glue various things together. For example, the CI might use scripts from workflow files, as opposed to running commands directly. This has the benefit that commands can be run in the same way in different places. If necessary, scripts are placed in a relevant subfolder.

Then there is the tests folder. Should be pretty self-explanatory what goes in here, again subdirectories are created as necessary. Preferably these subfolders group tests by the relevat project, e.g. tests/zcom would contain high-level system tests for the zcom executable.

Next up is tools. The difference between tools and scripts is that a script acts as glue, while a tool provides a distinct piece of functionality. For example, a tool might convert data files. Therefore, a script may one or more tools, but a tool would not call a script.

Last, but not least, there is the www directory. That’s where the sources for this website are located.