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.
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)
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:
$ sudo apt install build-essential cmake
$ mkdir build
$ cd build
$ cmake ..
$ make
$ ctest --output-on-failure
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
:
vcpkg integrate install
vcpkg install boost:x64-windows
From Visual Studio, configure the project to use the vcpkg toolchain file:
File -> Open -> Folder
, and select this projectCMake -> Change CMake Settings -> Template
x86
targets; just keep both x64
targetsx64
targets:
"variables": [
{
"name": "CMAKE_TOOLCHAIN_FILE",
"value": "C:\\vcpkg\\scripts\\buildsystems\\vcpkg.cmake"
}
],
Build the project and run the tests:
CMake -> Build All
CMake -> Tests -> Run Template CTests
This template C++ project implements a single function, get_nth_prime
, within
the namespace cpp_template
.
Note1: It is good practice in C++ to put all your code within a namespace, so that definitions in separate projects do not conflict with each other.
Note2: get_nth_prime
simply wraps the Boost prime number
implementation
Note3: To start using this template in your own projects, simply replace
these files with your own, and make sure to update the filenames in
CMakeLists.txt
.
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.
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
.add_executable
CMake function (in
CMakeLists.txt
), exactly like we have done for MyTests.cpp
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:
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
For windows testing we use AppVeyor, testing with just a single windows configuration:
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 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 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.
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!
If you have any feedback or suggestions about this project, please get in touch or open an issue.