CMake Starter

A minimalistic template to start a new CMake project.

This template provides a minimal sample CMake project that supports installation and testing. The project mainly consists of a CMake module that provides functions for use by other CMake projects.

In this template, the sample project is named MyProject, which includes a sample MyProject.cmake module. The module contains a sample git_clone function that can be used to clone a Git repository to a specific directory.

Key Features

• Provides a minimalistic CMake project with installation and testing support.
• Tests CMake variables and functions using Assertion.cmake.
• Preconfigured Dependabot and GitHub Actions workflows.

Usage Guide

The following guide shows how to use this template to start a new CMake project, from creation to release.

Create a New Project

Follow this link to create a new project using this template. It will create a new repository based on this template. Refer to this documentation for more information about creating a new repository from a template in GitHub.

Alternatively, you can also clone this repository locally to start using this template.

Choose a License

By default, this template is unlicensed. Before modifying this template, it is suggested to replace the LICENSE file with the license that will be used by the new project. Refer to this documentation for more information about licensing a repository.

Alternatively, you can also remove the LICENSE file or leave it as is to mark the new project as unlicensed.

Fill in Information

Do the following steps to replace all the sample information from the template with the new project information:

• Replace the content of this README.md file with the description of the new project. Refer to this documentation for more information about adding READMEs to a project.
• Rename the main module file (cmake/MyProject.cmake) to match the correct project name.
• Modify the package config file (cmake/MyProjectConfig.cmake) as follows:
  • Rename the file to match the correct project name.
  • Modify the content to include the correct main module file.
• Modify the test files (test/git_clone.cmake) to include the correct main module file.
• Modify the CMakeLists.txt file as follows:
  • Replace the project name, version, description, and homepage URL.
  • Rename the options to be prefixed with the correct project name.
  • Modify to include the correct main module file.
  • Rename the package version file to be prefixed with the correct project name.
  • Modify to install the correct files to the correct destination.
• Modify workflow files as follows:
  • Use the correct project name in the build.yaml workflow file.
  • Use the correct options in the test.yaml workflow file.

Note: You can also search for the TODO comments for a list of information that needs to be replaced.

Developing Modules

Modify the contents of the main module file (cmake/MyProject.cmake) with variables or functions provided by the new CMake project. If you are new to CMake, refer to this documentation for more information about CMake.

More module files can also be added under the cmake directory. Just make sure to add the new module files to the include list and install list in the CMakeLists.txt file and the package config file (cmake/MyProjectConfig.cmake).

After writing the module files, you can build the project using the following command:

cmake -B build

Testing Modules

Rename and modify the sample test file (test/git_clone.cmake) to test the variables and functions provided by the module files. The sample test file uses the Assertion.cmake module for testing CMake projects. Refer to this documentation for more information about testing CMake projects using Assertion.cmake.

More test files can also be added under the test directory. Just make sure to add the new test files to the test list in the CMakeLists.txt file.

After writing the test files, you can test the project using the following command:

cmake -B build -D MY_PROJECT_ENABLE_TESTS=ON
ctest --test-dir build --output-on-failure

Note: Replace the MY_PROJECT_ENABLE_TESTS option with the correct test option.

Cut a Release

When everything is complete, run the following command to install the new project to the install directory:

cmake --install build --prefix install

Files inside the install directory can be included in the release files. Before releasing, ensure that this project is at the correct version and pushed to the upstream repository. Refer to this documentation for more information about releasing a project.