C(++) W/ CMake and Google Test using GitHub actions Template

Usage

1. Creating a new repository

Click on the Use this template button on the top right of the repository page, and create a new repository as usual.

2. Changing template files

2.1. README.md

At the top of the README.md a couple of 'badges' are shown. These are generated by shields.io. You can change the badges to represent your project by changing the URL. For example: to change the Release badge, change the URL to:

![Release](https://img.shields.io/github/v/release/yourUsername/yourRepoName?label=Release&style=flat-square)

If you do not feel like changing the badges, you can remove them. Or if you feel like using different badges you can generate new ones at shields.io.

2.2. LICENSE

The LICENSE file is the license of the project. You can change it to another license, or remove it if you do not want to use a license.

It is recommended to use a pre-existing license, as it is difficult to write a license yourself.

2.3. CI.yml

The CI.yml file is the GitHub actions workflow file. It contains the steps that are executed when you push to the repository. Though it should work for most simple projects, you might want to change it to your liking.

2.4. .gitignore

The .gitignore file is used by git to ignore files that should not be tracked. The .gitignore provided should be sufficient for most simple projects.

2.5. CMake

The CMake files provided are meant to be a starting point for your project.

2.5.1. Main CMake

In this CMake file 3 variables are defined that should be edited on creation of a new project:

• ProjectName - The name of the project.
• ProjectRunName - The name of the program executable that is generated (this is postfixed with _Run).
• ProjectTestName - The name of the test executable that is generated (this is postfixed with _Test).

2.5.2. Source CMake

In this CMake file the source and header files are added to the project. You can add more source and header files to Sources and Headers respectively.

Note that files not included here will not be compiled or tested.

2.5.3. Test CMake

In this CMake file the test source files are added to the project. You can add more test source files to Sources.

3. Requirements

• CMake - The build system used.
  • Manual install of CMake may not be required in some cases such as when using Visual Studio Code.
• C/C++ Compiler of your choice.

4. Unit tests

This template uses Google Test. There is a sample unit test in the test folder.

5. Building

To run the program / tests you can use one of the following tools:

5.1. Command line

To build the project, run the following commands in the project folder:

mkdir ./build/

cmake -B ./build/ -DCMAKE_BUILD_TYPE=Debug

cmake --build ./build/ --target CHANGE_ME --config Debug

# To run tests:
cd ./build/

ctest

The above mentioned commands will build the project in debug mode. To build in release mode, replace Debug with Release.

If you want to build an executable, add _Run or _Test. See the CMake section for more information.

5.2. Visual Studio Code

Specific tools needed: CMake Tools (manages CMake install, CMake is not needed to be installed manually).

5.2.1. Running program

To build and run the project in Visual Studio Code, set the build target on the status bar (default located directly right of the Launch the selected target in the terminal window). Then press the Launch the selected target in the terminal window button.

5.2.2. Running tests

To build and run the tests in Visual Studio Code, press the CTest button in the status bar (default located to the right of the build target).

6. Adding / Removing files

6.1. Same folder as CMake file

If you decide to add a source / header file to the same folder as the CMake file, you will need to add the file to the sources / headers in the CMake file respectively.

Example:

Old:

set(Headers
    old_file.hpp
)

set(Sources
    old_file.cpp
)

New:

set(Headers
    old_file.hpp
    new_file.hpp
)

set(Sources
    old_file.cpp
    new_file.cpp
)

6.2. Adding / Removing files in subdirectories

If you decide to add a source / header file to a subdirectory, you will have to create a new CMake file in the subdirectory. This CMake file should contain the following:

cmake_minimum_required(VERSION 3.23.1)

set(Headers
    new_file.hpp
)

set(Sources
    new_file.cpp
)

add_library(ExampleLib STATIC ${Sources} ${Headers})

Example file provided here.

In the directory above the subdirectory, you will have to add a handful of things:

• Add the subdirectory using the add_subdirectory() command. Note that only one subdirectory can be added per add_subdirectory() command.
• Add the library to the target_link_libraries() command. Note that as many libraries can be added as you want, and that they are not limited to a subdirectory.

6.3. Including the new files

Keep in mind that none of these command will make any files globally known. Thus you still have to manually give the path to the file.

Example:

The file situation is as follows and we want to include Example2.hpp in main.cpp.

src/
├── Example/
│   ├── CMakeLists.txt
│   ├── example2.cpp
│   └── example2.hpp
├── CMakeLists.txt
├── example.cpp
├── example.hpp
└── main.cpp

Instead of being able to do:

#include "example2.hpp"

You will have to do:

#include "Example/example2.hpp"