docs/developer-guide.rst

   1 ..
   2 ..  Copyright (c) 2019 AT&T Intellectual Property.
   3 ..  Copyright (c) 2019 Nokia.
   4 ..
   5 ..  Licensed under the Creative Commons Attribution 4.0 International
   6 ..  Public License (the "License"); you may not use this file except
   7 ..  in compliance with the License. You may obtain a copy of the License at
   8 ..
   9 ..    https://creativecommons.org/licenses/by/4.0/
  10 ..
  11 ..  Unless required by applicable law or agreed to in writing, documentation
  12 ..  distributed under the License is distributed on an "AS IS" BASIS,
  13 ..  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 ..
  15 ..  See the License for the specific language governing permissions and
  16 ..  limitations under the License.
  17 ..
  18
  19
  20 ###############
  21 Developer Guide
  22 ###############
  23
  24 .. raw:: pdf
  25
  26    PageBreak
  27
  28 .. contents::
  29    :depth: 3
  30    :local:
  31
  32 .. raw:: pdf
  33
  34    PageBreak
  35
  36 Introduction
  37 ************
  38
  39 This is the developer guide of O-RAN SC SDL C++ library.
  40 SDL implementation downloading (execute command in such directory where you want
  41 to download SDL repository).
  42
  43 Without commit hook::
  44
  45     git clone "https://gerrit.o-ran-sc.org/r/ric-plt/sdl"
  46
  47 With commit hook::
  48
  49     git clone "https://gerrit.o-ran-sc.org/r/ric-plt/sdl" && (cd "sdl" && mkdir -p .git/hooks && curl -Lo `git rev-parse --git-dir`/hooks/commit-msg https://gerrit.o-ran-sc.org/r/tools/hooks/commit-msg; chmod +x `git rev-parse --git-dir`/hooks/commit-msg)
  50
  51
  52 SDL has only few dependencies to other components and therefore SDL should be
  53 quite simple to build and install to almost any modern Linux environment by
  54 following instructions below.
  55
  56 If not otherwise mentioned, commands in this document are executed in the
  57 directory where the SDL repository has been cloned into.
  58
  59 .. raw:: pdf
  60
  61    PageBreak
  62
  63 Compilation
  64 ***********
  65
  66 **Dependencies**
  67
  68 C++ compiler supporting C++14 is required for compiling SDL.
  69
  70 Currently, the following library is required while building:
  71
  72 * boost
  73 * hiredis
  74 * doxygen (optional)
  75
  76 Commands to install dependent packages in Fedora::
  77
  78     sudo dnf install boost-devel
  79     sudo dnf install hiredis-devel
  80     sudo dnf install doxygen
  81
  82 Commands to install dependent packages in Debian/Ubuntu::
  83
  84     sudo apt install libboost-all-dev
  85     sudo apt install libhiredis-dev
  86     sudo apt install doxygen
  87
  88 **Compilation in the Source Directory**::
  89
  90     ./autogen.sh
  91     ./configure
  92     make all
  93     make test
  94
  95 **Compilation in a Separate Build Directory**
  96
  97 Both *configure* and *make* can be executed in a separate directory
  98 (or directories) for keeping the source directory clean or for testing
  99 different configuration options in parallel. For example::
 100
 101     ./autogen.sh
 102     mkdir build
 103     cd build
 104     ../configure
 105     make all
 106     make test
 107
 108 Note that if you compile SDL this way, all coming *configure* and *make*
 109 commands are executed in the build directory like above.
 110
 111 .. raw:: pdf
 112
 113    PageBreak
 114
 115 Installation
 116 ************
 117
 118 By default the shared library is installed to */usr/local/lib* and headers into
 119 to */usr/local/include*. If this is not desired, then provide different path
 120 when running *configure*, for example::
 121
 122     ./configure --prefix=$HOME
 123
 124 Note that *configure* command allows plethora of additional options. For more
 125 info::
 126
 127     ./configure --help
 128
 129 After configuration has been done, run::
 130
 131     make install
 132
 133 .. raw:: pdf
 134
 135    PageBreak
 136
 137 .. _building_sdl_api_doc:
 138
 139 Building SDL API Document
 140 *************************
 141
 142 SDL API Documentation is a Doxygen document generated from SDL public header
 143 files.
 144
 145 One can generate Doxygen documentation locally by running commands::
 146
 147     ./autogen.sh
 148     ./configure
 149     make doxygen-doc
 150
 151 in the directory where the SDL repository has been cloned to.
 152
 153
 154 By default make doxygen-doc creates HTML, PDF and PS documents (if the needed
 155 tools are available, check the output of *./configure* command to get the names
 156 of missing tools). The documents are created to (paths are relative to the
 157 directory where the SDL repository has been cloned to):
 158
 159 * doxygen-doc/html/index.html
 160 * doxygen-doc/shareddatalayer.pdf
 161 * doxygen-doc/shareddatalayer.ps
 162
 163
 164 Creation of different document formats can be controlled with various
 165 --enable-doxygen-* and --disable-doxygen-* configuration options. For example
 166 if only HTML document is needed, then run::
 167
 168     ./configure --disable-doxygen-pdf --disable-doxygen-ps
 169     make doxygen-doc
 170
 171 .. raw:: pdf
 172
 173    PageBreak
 174
 175 Running Tests
 176 *************
 177
 178 Unit Tests
 179 ==========
 180
 181 Unit tests are compiled and executed by simply running::
 182
 183     make test
 184
 185 By default all unit tests are executed. If *valgrind* is installed, then by
 186 default unit test execution is analyzed with *valgrind*.
 187
 188 Running specific test cases can be achieved by using *GTEST_FILTER* environment
 189 variable. For example::
 190
 191     make test GTEST_FILTER=AsyncStorageTest*
 192
 193 If *valgrind* is not desired (even if installed), then it can be disabled with
 194 *USE_VALGRIND* environment variable::
 195
 196     make test USE_VALGRIND=false
 197
 198 Additional *valgrind* arguments can be specified with *VALGRIND_EXTRA_ARGS*
 199 environment variable. For example::
 200
 201     make test VALGRIND_EXTRA_ARGS='--track-fds=yes --log-file=mylog.txt'
 202
 203 It is also possible to use the *testrunner* binary directly (after it has been
 204 compiled). The *testrunner* binary supports all the command line options gtest
 205 supports, for example::
 206
 207     make testrunner
 208     ./testrunner --help
 209     ./testrunner
 210     ./testrunner --gtest_filter=AsyncStorageTest*
 211
 212 To get unit test code coverage analysis enable unit test gcov code coverage
 213 analysis by configuring gcov reporting directory::
 214
 215     configure --with-gcov-report-dir=DIR
 216
 217 Directory can be an absolute path or a relative path to an SDL source root.
 218 Unit test build creates directory if it does not exist.
 219
 220 Build and run unit tests with code coverage analysis::
 221
 222     make test_gcov
 223
 224 After successful unit test run code coverage (.gcov) result files are in
 225 a directory, what was defined by '--with-gcov-report-dir' configure option.
 226
 227 In addition, graphical gcov front-ends such as lcov can be used for coverage
 228 analysis::
 229
 230     lcov --directory tst/ --directory src --capture --output-file coverage.info
 231     genhtml coverage.info --output-directory out
 232
 233 Open the out/index.html using any web browser.
 234
 235
 236 Docker Tests
 237 ============
 238
 239 It's also possible to test SDL compilation, run unit tests and test building of
 240 rpm and Debian packages in a Docker::
 241
 242     docker build  --no-cache -f docker_test/Dockerfile-Test -t sdltest:latest .
 243
 244 If needed, ready rpm and Debian packages can be copied from Docker to host. In
 245 below example packages are copied to host's /tmp/sdltest-packages directory::
 246
 247     docker run -v /tmp/sdltest-packages:/export sdltest:latest /export
 248
 249 Functional Tests
 250 ================
 251
 252 Functional tests are not yet available.
 253
 254 .. raw:: pdf
 255
 256    PageBreak
 257
 258 Debugging SDL Binaries
 259 **********************
 260
 261 The testrunner and other binaries created by make into the working
 262 directory are not real binaries but shell scripts (generated by automake)
 263 used for running the real binaries. The real binaries are in .libs directory.
 264 Normally this is not important, but when using gdb or other debugger/analyzer
 265 tools it is important to use the real binary instead of the generated shell
 266 script.
 267
 268 Examples below demonstrate how one can run testrunner binary (unit tests) in
 269 gdb debugger::
 270
 271     LD_LIBRARY_PATH=.libs gdb --args .libs/testrunner
 272     LD_LIBRARY_PATH=.libs gdb --args .libs/testrunner --gtest_filter=AsyncStorageTest*
 273
 274 .. raw:: pdf
 275
 276    PageBreak
 277
 278 Redis
 279 *****
 280
 281 When Redis type backend data storage is used, SDL requires Redis v4.0 or
 282 greater. Older versions do not support extension modules.
 283
 284 Redis Modules
 285 =============
 286
 287 When Redis type backend data storage is used, SDL requires that the following
 288 Redis extension commands have been installed to runtime environment:
 289
 290 * MSETPUB
 291 * SETIE
 292 * SETIEPUB
 293 * SETNXPUB
 294 * DELPUB
 295 * DELIE
 296 * DELIEPUB
 297
 298 Implementation for these commands is produced by RIC DBaaS. In official RIC
 299 deployments these commands are installed by DBaaS service to Redis
 300 container(s). In development environment you may want install commands
 301 manually to pod/container which is running Redis.
 302
 303 **Manual Redis module installing**
 304
 305 Redis module implementation downloading (execute command in such directory
 306 where you want to download redis module implementation)::
 307
 308     git clone "https://gerrit.o-ran-sc.org/r/ric-plt/dbaas"
 309
 310 Installation to default system directory::
 311
 312     cd redismodule
 313     ./autogen.sh
 314     ./configure
 315     make install
 316
 317 Following line should be added to *redis.conf* file::
 318
 319     loadmodule <path>/libredismodule.so
 320
 321 <path> should be replaced to match library installation directory path.
 322
 323 *redis-server* must be restarted after configuration file update.
 324
 325 Notice that *redis-server* takes path to configuration file as an argument.
 326 If not given, *redis-server* will start with default parameter values and above
 327 made *loadmodule* option is not effective. Refer to::
 328
 329     redis-server --help
 330
 331 SDL API will check in connection setup phase that all required Redis extension
 332 commands are available, if not then execution is aborted and error log is
 333 written to identify which commands are missing.
 334
 335 .. raw:: pdf
 336
 337    PageBreak