doc/devenv.dox

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