OxfordRSE / template-project-cpp

An template C++ project using CMake for build configuration and Catch/TravisCI for automated testing
Other
25 stars 8 forks source link
address-sanitizer appveyor boost clang-tidy cmake codecov cpp linux travis visual-studio

Template C++ Project

codecov Build
Status Build status

Overview

This repository is a template to help get you set up quickly when starting a new C++ project. We have tried to conform to common software engineering 'best practices', and to that end this repository features the following:

In addition, the project is set up to use the boost libraries, and we will hopefully add other common libraries to the configuration soon.

Getting started

We strongly recommend that you use git to keep your copy of this project under version control.

Feel free to:

Note: if you just Fork this repository then it will not be independent of the original repo (i.e. no separate GitHub issues)

Where does it run?

We expect this project to be usable on all modern systems It is regularly tested on the following operating systems:

and with the following C++ compilers/toolchains:

First run

Linux

$ sudo apt install build-essential cmake
$ mkdir build
$ cd build
$ cmake ..
$ make
$ ctest --output-on-failure

macOS

Windows

First, install the following software:

Next, we assume the use of Microsoft's C++ package manager, vcpkg, for installing dependencies. The following instructions assume you install vcpkg to C:\vcpkg:

From Visual Studio, configure the project to use the vcpkg toolchain file:

Build the project and run the tests:

Documentation

MyLibrary.{hpp,cpp}

This template C++ project implements a single function, get_nth_prime, within the namespace cpp_template.

Exception.h

The argument to get_nth_prime must be greater than zero, and less than boost::math::max_prime. If either of these conditions are not satisfied the function throws an exception, which is defined in this file.

MyTests.cpp

Write the unit tests for your code here. Our example uses the Catch framework, and includes tests that check the accuracy of the get_nth_prime function, and check that the function throws the appropriate exceptions on invalid input.

CMakeLists.txt

CMake is a cross-platform build configuration tool, which generates compilation scripts (e.g. using Makefiles in linux, or Visual Studio projects for windows) that you can run to compile your C++ project.

Edit the CMakeTests.txt configuration file to do things like:

.travis.yml

This template uses Travis CI for automated testing. This is fully defined in the .travis.yml file and includes:

The results of the automated testing are reported on the Travis CI project page

appveyor.yml

For windows testing we use AppVeyor, testing with just a single windows configuration:

codecov

Code coverage allow you to see how much of your code is actually covered by your test suite. That is, which lines of code are actually run during the tests.

To do this, the code must be compiled with compiler flags that allow the executable to collect information about which lines of code are called during execution. For GCC or Clang this means adding the --coverage flag, which is done in the CMakeLists.txt configuration file.

You can see the .travis.yml for an example of how to collect the coverage data in a readable format using lcov (see the "after_success:" section). This data is then sent to codecov for an even easier-to-read web interface.

.clang-format

Clang Format is a tool to automatically format your code according to a set style configuration. This is incredibly useful because it frees you up from having to worry about things like indenting, spacing out your code or breaking long lines of code, just type in your code and let Clang Format clean it up for you.

You can install Clang Format on Ubuntu using apt:

$ sudo apt install clang-format

You can set the particular style you wish to apply using the .clang-format configuration file. The clang-format configurator is a useful web app for generating this file.

Note that most IDEs will allow you to automatically run Clang Format when the file is saved, which even saves you from manually running the tool in the first place.

.clang-tidy

Clang Tidy is a clang-based C++ linter tool. A linter will analyzing your code to check for common programming bugs and stylistic errors. This might seem similar to the warnings often given by the compiler, but a linter will have a much more comprehensive set of tests that examines the structure of your code rather than the often line-by-line checking done by the compiler.

You can install Clang Tidy on Ubuntu using apt:

$ sudo apt install clang-tidy

The .clang-tidy configuration file allows you to set or turn off individual or sets of checks done by clang-tidy. We also setup the CMakeLists.txt file so that clang-tidy is run automatically during compile-time.

AddressSanitizer

There is an optional component enabled via CMake that can use the LLVM AddressSanitizer to detect memory errors. This is turned on by default for the clang builds on Travis, so you will see any errors on there if it's configured.

You can also run it yourself, provided you are using the clang compiler, by using the Template_MEMCHECK option when running CMake. Simply enable the option, then configure, build, and test:

cmake -DTemplate_MEMCHECK=TRUE /path/to/project
make
ctest

The test will fail at the first error. It is unlikely that you will encounter a false positive when using the address sanitizer, so if you do see an error, best not to ignore it!

Feedback and suggestions

If you have any feedback or suggestions about this project, please get in touch or open an issue.