doc/devenv.dox

   1 /**
   2
   3 \page development_environment Development Environment
   4
   5 \tableofcontents
   6
   7 This page describes the requirements in order to build the library.
   8
   9 \subsection subsec_devenv_requirements Requirements
  10 Compiler supported (older/others may work, but not tested):
  11 - GCC 4.9
  12 - GCC 5
  13 - GCC 6
  14 - GCC 7
  15 - GCC 8
  16 - GCC 9
  17 - GCC 10
  18 - GCC 11
  19 - Clang 4
  20 - Clang 5
  21 - Clang 6
  22 - Clang 7
  23 - Clang 8
  24 - Clang 9
  25 - Clang 10
  26 - Clang 11
  27 - Clang 12
  28
  29 Tools needed to build the library:
  30 - cmake 3.11 or newer
  31
  32 Tools needed to develop the library:
  33 - git
  34 - clang-format 3.9
  35
  36 Tools needed to build the documentation:
  37 - doxygen
  38 - graphviz
  39 - LaTeX (there are formulas!)
  40
  41 optional (used for development only):
  42 - lcov / genhtml, c++filt
  43 - cppcheck
  44 - clang-tools (analyzer)
  45 - ctags, cscope
  46 - perf
  47
  48 optional (no core dependency):
  49 - Boost.ASIO (used only for some examples)
  50 - Qt 5 (used only for some examples)
  51
  52 There are no other dependencies despite the standard library (C++11) to build this library.
  53
  54 Other compilers may work, however untested.
  55
  56 \subsection subsec_devenv_build Build
  57 For normal, debug and release builds use the standard cmake CMAKE_BUILD_TYPE variable.
  58 For example a debug build:
  59
  60 Full information developpers build:
  61 \code
  62         mkdir build
  63         cd build
  64         cmake -DCMAKE_BUILD_TYPE=Coverage ..
  65         make
  66         make coverage doc cppcheck
  67 \endcode
  68
  69 Debug build:
  70 \code
  71         mkdir build
  72         cd build
  73         cmake -DCMAKE_BUILD_TYPE=Debug ..
  74         make
  75 \endcode
  76
  77 If you like to perform code coverage using the unit tests, do:
  78 \code
  79         mkdir build
  80         cd build
  81         cmake -DCMAKE_BUILD_TYPE=Coverage ..
  82         make
  83         make coverage
  84 \endcode
  85
  86 As packaging system, cpack is used. Do after build:
  87 \code
  88         make package
  89 \endcode
  90
  91 or for individual package types:
  92
  93 \code
  94         cpack -G TGZ
  95         cpack -G DEB
  96 \endcode
  97
  98 Build documentation:
  99 \code
 100         mkdir build
 101         cd build
 102         cmake ..
 103         make doc
 104 \endcode
 105
 106 After proper building and execution:
 107 - [Code Coverage](../coverage/index.html)
 108 - [cppcheck](../cppcheck.txt)
 109 - [Doxygen Warnings](../doxygen-warnings.txt)
 110
 111
 112 \subsection subsec_devenv_buildoptions Build Options
 113 The following build types (-DCMAKE_BUILD_TYPE=x) are possible:
 114 - Debug
 115 - Release
 116 - Coverage
 117
 118 Build options:
 119 - `ENABLE_STATIC` : enables static build, if `OFF`, a shared library is being built.
 120   Default: `ON`
 121 - `ENABLE_PROFILING` : enables profiling for `gprof`
 122 - `ENABLE_BENCHMARK` : enables benchmarking (disables some optimization)
 123 - `ENABLE_SANITIZER` : enables address and undefined sanitizers
 124
 125 Features:
 126 - `ENABLE_IO` : enables IO support. Default: `ON`
 127
 128 Components:
 129 - `ENABLE_EXAMPLES`: enables examples. Default: `ON`
 130 - `ENABLE_TESTS`: enables unit tests, integration tests and benchmarks. Default: `ON`
 131 - `ENABLE_TOOLS`: enables tools. Default: `ON`
 132
 133
 134 \subsection subsec_devenv_clang_static_analysis Static Analysis with Clang
 135 There is a script ```bin/static-analysis-clang``` for doing this, or do it manually:
 136 \code
 137         mkdir build
 138         cd build
 139         cmake -DCMAKE_CXX_COMPILER=/usr/share/clang/scan-build-3.9/libexec/c++-analyzer ..
 140         scan-build-3.9 -o doc/analysis --use-analyzer=/usr/bin/clang++-3.9 make
 141 \endcode
 142
 143 After the build, ```scan-build``` will tell you what to do in order to inspect
 144 the findings.
 145
 146
 147 \subsection subsec_devenv_benchmarks Perform Benchmarks
 148 Build in ```Release``` mode, perform individual benchmarks:
 149 \code
 150         mkdir build
 151         cd build
 152         cmake -DCMAKE_BUILD_TYPE=Release ..
 153         make -j 8
 154         test/benchmark_nmea_split
 155 \endcode
 156
 157 Using `perf` to do performance analysis:
 158 \code
 159         mkdir build
 160         cd build
 161         cmake -DCMAKE_BUILD_TYPE=Release -DENABLE_BENCHMARK=ON ..
 162         make -j 8
 163         perf record -g test/benchmark_nmea_split
 164         perf report -g 'graph,0.5,caller'
 165 \endcode
 166
 167 */