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