Merge pull request #13 from Flamefire/improve_example

Improve example

Author: thomasrockhu

.travis.yml

@@ -2,24 +2,33 @@ language: cpp
 os: linux
 compiler: gcc
 
+cache: # see https://docs.travis-ci.com/user/caching/
+- directories:
+  - $HOME/.cache
+
 addons:
   apt:
     packages: lcov
 
-before_script:
-- mkdir -p build && cd build
+install:
+# (fake) install dependencies (usually involves wget, configure, make, ...)
+# install into cache folder (build binaries+headers only, no sources and do NOT build there)
+- mkdir -p $HOME/.cache
+- touch $HOME/.cache/mydependency.so
 
-script:
-- cmake -DCODE_COVERAGE=ON ..
-- cmake --build . --config Debug -- -j $(nproc)
-- ctest -j $(nproc) --output-on-failure
+script: ./build.sh
 
 after_success:
 # Create lcov report
-- lcov --capture --directory . --output-file coverage.info
-- lcov --remove coverage.info '/usr/*' --output-file coverage.info # filter system-files
+# capture coverage info
+- lcov --directory . --capture --output-file coverage.info
+# filter out system and extra files.
+# To also not include test code in coverage add them with full path to the patterns: '*/tests/*'
+- lcov --remove coverage.info '/usr/*' "${HOME}"'/.cache/*' --output-file coverage.info
+# output coverage data for debugging (optional)
 - lcov --list coverage.info
 # Uploading to CodeCov
+# '-f' specifies file(s) to use and disables manual coverage gathering and file search which has already been done above
 - bash <(curl -s https://codecov.io/bash) -f coverage.info || echo "Codecov did not collect coverage reports"
 
 notifications:

CMakeLists.txt

@@ -1,21 +1,18 @@
-cmake_minimum_required (VERSION 3.0)
+cmake_minimum_required (VERSION 3.1)
 project(Example LANGUAGES CXX)
 
-option(CODE_COVERAGE "Enable coverage reporting" OFF)
-
-# Common configuration and force C++ standard
-add_compile_options(-Wall -pedantic)
-if(CMAKE_VERSION VERSION_GREATER_EQUAL 3.1)
-  set(CMAKE_CXX_STANDARD 11)
-else()
-  add_compile_options(-std=c++11)
-endif()
-
+# Use C++11
+set(CMAKE_CXX_STANDARD 11)
+# Require (at least) it
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+# Don't use e.g. GNU extension (like -std=gnu++11) for portability
+set(CMAKE_CXX_EXTENSIONS OFF)
 
 # Code Coverage Configuration
 add_library(coverage_config INTERFACE)
 
-if(CODE_COVERAGE)
+option(CODE_COVERAGE "Enable coverage reporting" OFF)
+if(CODE_COVERAGE AND CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")
   # Add required flags (GCC & LLVM/Clang)
   target_compile_options(coverage_config INTERFACE
     -O0        # no optimization
@@ -30,5 +27,13 @@ if(CODE_COVERAGE)
 endif(CODE_COVERAGE)
 
 
-enable_testing() # CTest
 add_subdirectory(src)
+
+option (BUILD_TESTING "Build the testing tree." ON)
+# Only build tests if we are the top-level project
+# Allows this to be used by super projects with `add_subdirectory`
+if (BUILD_TESTING AND (PROJECT_SOURCE_DIR STREQUAL CMAKE_SOURCE_DIR))
+  enable_testing()
+  add_subdirectory(tests)
+endif()
+

README.md

@@ -16,7 +16,7 @@ The goal of this project is to build project with following tools:
  * Source: multiple files
 
 ## Special Thanks
-Goes to [Richel Bilderbeek](https://github.com/richelbilderbeek) for inspiration and all work on [Travis CI tutorials](https://github.com/richelbilderbeek/travis_cpp_tutorial). 
+Goes to [Richel Bilderbeek](https://github.com/richelbilderbeek) for inspiration and all work on [Travis CI tutorials](https://github.com/richelbilderbeek/travis_cpp_tutorial).
 Here is a [link](https://github.com/richelbilderbeek/travis_cmake_gcc_cpp11) to a project with the same structure (without `lcov`),
 and here is a [list](https://github.com/richelbilderbeek/travis_cpp_tutorial/blob/master/statuses.md) of all his Travis configuration examples.
 
@@ -61,9 +61,25 @@ after_success:
   - bash <(curl -s https://codecov.io/bash) -t uuid-repo-token
 ```
 
+## Example details
+This repo can serve as the starting point for a new project. The following is worth noticing:
+1. Use of a build script instead of putting the commands into `.travis.yml`
+  - Allows local testing
+  - Allows usage of `set -e` to error out with meaningfull messages on any command failure
+2. Separate testing source tree
+  - Allows to easily enable/disable testing
+  - Allows usage in parent projects (you don't want to build the tests if you are consumed)
+  - You may want to exclude coverage of test files which is easier when they are in a separate folder.
+    Remember to use **full paths** for patterns (like `'*/tests/*'`)
+3. Use of travis cache to cache manually build 3rd-party dependencies (like boost)
+  - Speeds up build
+  - More can be added (e.g. `ccache`)
+  - Those need to be excluded from coverage info too
+
 ## Authors
 * **RokKos** - [RokKos](https://github.com/RokKos)
 * **Rolf Eike Beer** - [DerDakon](https://github.com/DerDakon)
+* **Alexander Grund** - [Flamefire](https://github.com/Flamefire)
 
 ## License
 This project is licensed under the MIT License - see the [LICENSE](https://github.com/RokKos/classes-c-/blob/master/LICENSE) file for details.

build.sh

@@ -0,0 +1,13 @@
+#!/bin/bash
+
+set -euo pipefail
+
+mkdir -p build && cd build
+
+# Configure
+cmake -DCODE_COVERAGE=ON -DCMAKE_BUILD_TYPE=Debug ..
+# Build (for Make on Unix equivalent to `make -j $(nproc)`)
+cmake --build . --config Debug -- -j $(nproc)
+# Test
+ctest -j $(nproc) --output-on-failure
+

src/CMakeLists.txt

@@ -1,13 +1,7 @@
-cmake_minimum_required(VERSION 3.0)
-
-# The library
 add_library(example complex.cpp)
 target_include_directories(example PUBLIC ${CMAKE_CURRENT_SOURCE_DIR})
+# Setting this to the library only avoids errors in 3rd party dependencies which are compile with e.g. -Werror
+target_compile_options(example PUBLIC -Wall -pedantic)
 # Include code-coverage settings:
 target_link_libraries(example PUBLIC coverage_config)
 
-
-# Tests for the library
-add_executable(tests complex_main.cpp)
-target_link_libraries(tests PRIVATE example) # inherits coverage_config
-add_test(NAME example_test COMMAND tests)

tests/CMakeLists.txt

@@ -0,0 +1,6 @@
+add_executable(tests complex_main.cpp)
+# Linking up all libraries (includes the coverage settings set by 'example' library)
+target_link_libraries(tests PRIVATE example)
+
+add_test(NAME example_test COMMAND tests)
+