sample-cpp-project

A C++ project template, utilizing:

• Automatic Formatting (Clang-Format)
• Linting & Static Analysis (Clang-Tidy, Include What You Use, Cppcheck)
• Sanitizers (ASAN)
• Unit Testing (Catch2)
• Benchmarking (Catch2)
• Continuous Integration (Travis CI)
• Code Coverage Reporting (Codecov)
• Documentation Generation & Hosting (Doxygen, Sphinx, Read the Docs)

Prerequisites

To build the library you need:

• CMake
• vcpkg (optional)

To build the documentation, you also need:

• Doxygen
• Pip (optional)

Installing dependencies

• If you want to build tests and/or benchmarks, run:

  vcpkg install catch2

  If you did not install vcpkg, you need an alternate method of getting:

  • Catch2

• If you want to build documentation, run:

  pip install sphinx
  pip install sphinx_rtd_theme
  pip install recommonmark
  pip install breathe

  If you do not install Pip, you need an alternate method of getting:

  • Sphinx
  • Sphinx_rtd_theme
  • recommonmark
  • Breathe

Building

First, clone the repo and create a build folder

git clone https://github.com/s-nandi/sample-cpp-project.git
cd sample-cpp-project
mkdir build
cd build

Then, run

cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=/path/to/your/vcpkg.cmake

you can pass in-DBUILD_TESTS=ON, -DBUILD_BENCHMARKS=ON, and -DBUILD_DOCUMENTATION=ON to build tests, benchmarks, and/or documentation respectively

And finally, build the project

cmake --build . --config Release

---

In order to run the tests, use the following line: ctest -C Release --output-on-failure

To run the benchmarks, go to build/benches and run the benchmarks executable.

The root documentation file is build/docs/sphinx/index.html.

Setting up for your own project

• You might want to change the language standard (set to C++17 by default) in CMakeLists.txt

• You can modify the compiler flags used in scripts/cmake/SetProjectCompileOptions.cmake

• The project and author names must be set manually in docs/source/conf.py, similarly the project name must be set in CMakeLists.txt (the project name in conf.py MUST be identical to the project name in CMakeLists.txt)

• Modify the library's source files in the root CMakeLists.txt file:

set(${PROJECT_NAME}_SOURCE_FILES
        # List source files below
        src/library.cpp
        include/sample_cpp_project/library.hpp
        additional source files go here)

• List the files that should prompt Sphinx to regenerate documentation when changed, by modifying the sphinx target's dependency list in docs/CMakeLists.txt:

add_custom_target(${SPHINX_TARGET_NAME} ALL
        ...
        # List documentation files below
        source/index.rst
        additional documentation files go here)

• Note that only public header files are documented (ie. the .h/.hpp files in include/ but NOT the ones in /src)

• You will need to host the project on travis CI, codecov, and Read the Docs yourself.

Acknowledgment

Ideas were taken from:

• Doctest's .travis.yml
• Simon Brand's article on clean c++ documentation