README.in.adoc

@PROJECT_NAME@

Table of Contents

• Copyright
• About
• Documentation
  • Usage
• Contribution
  • Issues
  • Directory Layout
  • File Name Conventions
  • Conventional Commits

Copyright

{copyright}

About

@PROJECT_DESCRIPTION@

Documentation

Usage

git subtree

CMake FetchContent

git submodule

Copy & Paste

The methods above are preferred for sure. But as a last resort, you may of course use the @PROJECT_NAME@ snippets by storing them into your project’s file structure.

If your project has a Directory Layout similar to this project’s, the right place should be external/cmake-essential.

Contribution

Issues

Please use the hosting website to track @PROJECT_HOMEPAGE_URL@/-/issues[issues].

Directory Layout

CMakeLists.txt and its includes try to follow ideas from The optimal CMake project structure by Stanislav Arnaudov.

More importantly, this project aims to adhere to The Pitchfork Layout (PFL) by Colby Pike. This is also the source for the following directory description (though they were adapted to this specific project):

PFL prescribes several directories that should appear at the root of the project tree. Not all of the directories are required, but they have an assigned purpose, and no other directory in the filesystem may assume the role of one of these directories. That is, these directories must be the ones used if their purpose is required.

Other directories should not appear at the root. — Empty directories are not stored.

include/

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. — Contains the "essential" *.cmake files required by projects that consume @PROJECT_NAME@.

data/

Directory containing non-source code aspects of the project. This might include graphics and markup files. — Contains the logo.

tools/

Directory containing development utilities, such as build and refactoring scripts. — Contains templates to generate the CMake module files:

• tools/CMakeLists.in.cmake → CMakeLists.txt

• tools/CMakeEssential.in.cmake → CMakeEssential.cmake

• tools/CMakeEssentialConfig.in.cmake → CMakeEssentialConfig.in.cmake

docs/

Directory for project documentation. — Contains templates to generate the documentation:

• docs/README.in.adoc → README.adoc

File Name Conventions

Who has ever tried to find the underscore on a foreign keyboard? I (Max) have, and it is cumbersome.

So, here are the most important rules for filenames:

1. Filename rules apply to names of folders.

2. No whitespace in filenames.

3. No "foreign" characters in filenames. Stick to [a-zA-Z0-9_.-+].

4. Avoid unnecessary abbreviations.

5. Separate words preferably with a single dash "-".

6. No underscores in examples.

7. No underscores in executables. — Neither in scripts, which are executables for that matter.

8. No uppercase in executables. — Not even "UML" :-(

9. Avoid uppercase letters, whenever it’s not (really) helping.

   1. Exception: README.adoc, LICENSE.adoc — these must stick out.

   2. Exception: CMakeFile and friends — it’s conventional for those.

   3. Exception: QML-files — Qt requires it.

10. No extension for (bash) scripts — Because Commandname Extensions [are] Considered Harmful.

Conventional Commits

Developers are encouraged to adhere to the Conventional Commits "[…​] specification for adding human and machine readable meaning to commit messages".