Template for starting a C/C++ CMake project.
All features are optional
- Code formatting via clang-format
- Unit testing using CTest & Google Test
- Faster compilation using CCache
- Directory structure prepared for typical use cases
- Example setup for
- a hello world program
- finding external packages like Boost
- generating unit tests
Goal of all this is to provide a starting point for a C/C++ CMake projekt and to reduce repetitive boilerplate that is necessary every time a new project is started. The template aims to be configurable for your needs and provides examples for e.g. finding packages or adding CMake targets. Some parts can simply be activated by uncommenting the code, others can be enabled or disabled in a config section / by passing some arguments when calling cmake.
Feel free to use the template and adjust it to your needs.
The template uses replaceme
as indicator that this file / directory / string should be
yet replaced by your project name. You don't have to do that manually, there are scripts
that can do that. See Installation.
The following directories are already available for the purposes shown below:
├── ci/ # For continuous integration files
├── cmake/ # For CMake macros / scripts
├── doc/ # For documentation
├── example/ # For example programs
├── script/ # For utility bash/powershell scripts
├── include/
│ └── replaceme/ # For public header files
├── src/ # For .cpp files and private headers
└── test/ # For unit tests
-
Clone this repository into an empty directory:
Using HTTPS:$ git clone https://github.com/hey-sebi/modern-cmake-template.git
Using SSH:
$ git clone [email protected]:hey-sebi/modern-cmake-template.git
-
Use a script matching your operating system in order to replace template values / directory names with the name of your project. These scripts will ask you for the project name and also delete the
.git
directory so that you can setup your own version control.
From the repository root directory run- on Linux/MacOS
$ ./script/setup_project.sh <yourprojectname>`
- on Windows
$ ./script/setup_project.ps1 <yourprojectname>`
You should use a project name without spaces here.
- on Linux/MacOS
-
Delete the
script/setup_project.*
files as you probably don't need them anymore.
The repository contains a simple "hello world" program that you can use to test if
compilation works or as example on how to build an executable. See src
directory.
In addition there is an example unit test in the test
directory.
There is a version header file version.h
which defines the project's version according
to a semantic versioning scheme (see also https://semver.org/). This way, you can use
the version number in your code, e.g. for logging or similar. Simply change the numbers
in this file to modify the version of the project.
There is a section called "Configuration" in the top-level CMakeLists.txt
where you can
see different aspects that can be configured. Alternatively you can overwrite the
configured values by passing -D<the-value>=off
or -D<the-value>=on
respecively. The
configuration section can also be extended to contain options for your project.
Code formatting is setup to be used with Clang
Format. The configuration file is
.clang-format
and is set to use the Google Style. Adjust it to your needs.
Skip this section if you are already familiar with CMake.
To trigger CMake, a typical approach would be:
- Create a build directory:
mkdir build
- Go to that directory:
cd build
- Call CMake:
cmake ..
The cmake
command takes the directory of a CMakeLists.txt as argument, so we provide the
parent directory.
This is called an out of source build, as generated files are not mixed with our source
code but instead placed into the build
directory, which is a good approach. You should
always use out of source builds, as it makes a lot of things easier, e.g. you will always
know what files to delete in order to force a 100% clean build.
You can use different generators with CMake. If no generator is provided, CMake works with Makefiles. A good alternative is using Ninja. In this case your cmake invokation would look like this:
$ cmake -GNinja ..
Other generators exist, e.g. for some IDEs as well. More information can be found at the official CMake website.
There are many CMake tutorials available online, so I won't go into detail here any further. A good starting point, especially regarding modern CMake style (available since CMake v3.0), is this digest: https://cliutils.gitlab.io/modern-cmake/