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 Functional Tests
 213 ================
 214
 215 Functional tests are not yet available.
 216
 217 .. raw:: pdf
 218
 219    PageBreak
 220
 221 Debugging SDL Binaries
 222 **********************
 223
 224 The testrunner and other binaries created by make into the working
 225 directory are not real binaries but shell scripts (generated by automake)
 226 used for running the real binaries. The real binaries are in .libs directory.
 227 Normally this is not important, but when using gdb or other debugger/analyzer
 228 tools it is important to use the real binary instead of the generated shell
 229 script.
 230
 231 Examples below demonstrate how one can run testrunner binary (unit tests) in
 232 gdb debugger::
 233
 234     LD_LIBRARY_PATH=.libs gdb --args .libs/testrunner
 235     LD_LIBRARY_PATH=.libs gdb --args .libs/testrunner --gtest_filter=AsyncStorageTest*
 236
 237 .. raw:: pdf
 238
 239    PageBreak
 240
 241 Redis
 242 *****
 243
 244 When Redis type backend data storage is used, SDL requires Redis v4.0 or
 245 greater. Older versions do not support extension modules.
 246
 247 Redis Modules
 248 =============
 249
 250 When Redis type backend data storage is used, SDL requires that the following
 251 Redis extension commands have been installed to runtime environment:
 252
 253 * MSETPUB
 254 * SETIE
 255 * SETIEPUB
 256 * SETNXPUB
 257 * DELPUB
 258 * DELIE
 259 * DELIEPUB
 260
 261 Implementation for these commands is produced by RIC DBaaS. In official RIC
 262 deployments these commands are installed by DBaaS service to Redis
 263 container(s). In development environment you may want install commands
 264 manually to pod/container which is running Redis.
 265
 266 **Manual Redis module installing**
 267
 268 Redis module implementation downloading (execute command in such directory
 269 where you want to download redis module implementation)::
 270
 271     git clone "https://gerrit.o-ran-sc.org/r/ric-plt/dbaas"
 272
 273 Installation to default system directory::
 274
 275     cd redismodule
 276     ./autogen.sh
 277     ./configure
 278     make install
 279
 280 Following line should be added to *redis.conf* file::
 281
 282     loadmodule <path>/libredismodule.so
 283
 284 <path> should be replaced to match library installation directory path.
 285
 286 *redis-server* must be restarted after configuration file update.
 287
 288 Notice that *redis-server* takes path to configuration file as an argument.
 289 If not given, *redis-server* will start with default parameter values and above
 290 made *loadmodule* option is not effective. Refer to::
 291
 292     redis-server --help
 293
 294 SDL API will check in connection setup phase that all required Redis extension
 295 commands are available, if not then execution is aborted and error log is
 296 written to identify which commands are missing.
 297
 298 .. raw:: pdf
 299
 300    PageBreak