README.md

   1 # shareddatalayer
   2
   3 ## Table of contents
   4
   5 - [Documentation](#documentation)
   6 - [Compilation](#compilation)
   7 - [Installation](#installation)
   8 - [Running unit tests](#running-unit-tests)
   9 - [Using SDL in application pod](#using-sdl-in-application-pod)
  10
  11 ## Documentation
  12
  13 Documentation is generated with `doxygen` tool. Dependency to `doxygen`
  14 tool is optional. If not installed, then `doxygen-doc` target will not
  15 be created to Makefile.
  16
  17 By default `make doxygen-doc` creates HTML, PDF and PS documents (if
  18 the needed tools are available). The documents are created to:
  19
  20 1. doxygen-doc/html/index.html
  21 2. doxygen-doc/shareddatalayer.pdf
  22 3. doxygen-doc/shareddatalayer.ps
  23
  24 Creation of different document formats can be controlled with various
  25 `--enable-doxygen-*` and `--disable-doxygen-*` configuration
  26 options. For example if only HTML document is needed, then run:
  27
  28     ./configure --disable-doxygen-pdf --disable-doxygen-ps
  29     make doxygen-doc
  30
  31 ## Compilation
  32
  33 These instructions assume that the project has been cloned into
  34 directory named `shareddatalayer`.
  35
  36 ### Dependencies
  37
  38 Build-time dependencies:
  39
  40     libboost (system, filesystem, program-options)
  41     hiredis
  42     rpm
  43     valgrind
  44     autoconf-archive
  45     doxygen (optional)
  46
  47 Commands to install dependent packages in Fedora:
  48
  49     sudo dnf install boost-devel
  50     sudo dnf install hiredis-devel
  51     sudo dnf install rpm
  52     sudo dnf install valgrind
  53     sudo dnf install autoconf-archive
  54     sudo dnf install doxygen
  55
  56 Commands to install dependent packages in Debian/Ubuntu:
  57
  58     sudo apt install libboost-filesystem-dev
  59     sudo apt install libboost-program-options-dev
  60     sudo apt install libboost-system-dev
  61     sudo apt install libhiredis-dev
  62     sudo apt install rpm
  63     sudo apt install valgrind
  64     sudo apt install autoconf-archive
  65     sudo apt install doxygen
  66
  67 ### Compilation in the source directory
  68
  69     cd shareddatalayer
  70     ./autogen.sh
  71     ./configure
  72     make all test
  73
  74 ### Compilation outside the source directory
  75
  76     cd shareddatalayer
  77     ./autogen.sh
  78     cd ..
  79     mkdir workdir
  80     cd workdir
  81     ../shareddatalayer/configure
  82     make all test
  83
  84 ## Installation
  85
  86 By default the shared library is installed to `/usr/local/lib` and
  87 headers into to `/usr/local/include`. If this is not desired, then
  88 provide different path when running `configure`, for example:
  89
  90     ./configure --prefix=$HOME/usr/local
  91
  92 In above example SDL pkg-config .pc file is installed to `$HOME/usr/local/lib/pkgconfig`
  93 directory. This directory should be included to `PKG_CONFIG_PATH` while building
  94 the application which is using the SDL API library.
  95
  96 Note that `configure` command allows plethora of additional options.
  97 For more info:
  98
  99     ./configure --help
 100
 101 After configuration has been done, run:
 102
 103     make install
 104
 105 In some cases dynamic linker cache needs to be manually refreshed after SDL API
 106 has been re-installed:
 107
 108     ldconfig
 109
 110 ### Redis modules
 111
 112 When Redis is used, SDL requires that the following Redis extension commands
 113 have been installed to runtime environment:
 114 - MSETPUB
 115 - SETIE
 116 - SETIEPUB
 117 - SETNXPUB
 118 - DELPUB
 119 - DELIE
 120 - DELIEPUB
 121
 122 Redis v4.0 or greater is required. Older versions do not support extension
 123 modules.
 124
 125 Implementation for these commands is produced by RIC DBaaS:
 126 https://gerrit.o-ran-sc.org/r/admin/repos/ric-plt/dbaas
 127
 128 In official RIC deployments these commands are installed by `dbaas` service to
 129 Redis container(s).
 130
 131 In development environment you may want install commands manually to pod/container
 132 which is running Redis.
 133
 134 Installation to default system directory:
 135
 136     cd redismodule
 137     ./autogen.sh
 138     ./configure
 139     make install
 140
 141 Following line should be added to `redis.conf` file:
 142
 143     loadmodule <path>/libredismodule.so
 144
 145 `<path>` should be replaced to match library installation directory path.
 146 `redis-server` must be restarted after configuration file update.
 147
 148 Notice that `redis-server` takes path to configuration file as an argument.
 149 If not given it will start with default parameter values and above made
 150 `loadmodule` option is not effective. Refer to `redis-server --help`.
 151
 152 SDL API will check in connection setup phase that all required commands are
 153 available, if not then execution is aborted and error log is written to identify
 154 that which commands are missing.
 155
 156 ## Running unit tests
 157
 158 Unit tests are compiled and executed by simply running:
 159
 160     make test
 161
 162 By default all unit tests are executed. If `valgrind` is installed,
 163 then by default unit test execution is analyzed with `valgrind`.
 164 Running specific test cases can be achieved by using `GTEST_FILTER`
 165 environment variable. For example:
 166
 167     make test GTEST_FILTER=ConnectionTest*
 168
 169 If `valgrind` is not desired (even if installed), then it can be
 170 disabled with `USE_VALGRIND` environment variable:
 171
 172     make test USE_VALGRIND=false
 173
 174 Additional `valgrind` arguments can be specified with `VALGRIND_EXTRA_ARGS`
 175 environment variable. For example:
 176
 177     make test VALGRIND_EXTRA_ARGS='--track-fds=yes --log-file=mylog.txt'
 178
 179 It is also possible to use the `testrunner` binary directly (after it
 180 has been compiled). The `testrunner` binary supports all the command
 181 line options gtest supports, for example:
 182
 183     make testrunner
 184     ./testrunner --help
 185
 186 ## Running unit tests with gcov
 187
 188 Enable unit test gcov code coverage analysis by configuring gcov reporting
 189 directory:
 190
 191     ./configure --with-gcov-report-dir=DIR
 192
 193 Directory can be an absolute path or a relative path to an SDL source root.
 194 Unit test build creates directory if it does not exist.
 195
 196 Build and run unit tests with code coverage analysis:
 197
 198     make test_gcov
 199
 200 After successful unit test run code coverage (.gcov) result files are in
 201 a directory, what was defined by '--with-gcov-report-dir' configure option.
 202
 203 In addition, graphical gcov front-ends such as lcov can be used for coverage
 204 analysis:
 205
 206     lcov --directory tst/ --directory src --capture --output-file coverage.info
 207     genhtml coverage.info --output-directory out
 208
 209 Open the out/index.html using any web browser.
 210
 211 ## Docker Tests
 212
 213 It's also possible to test SDL compilation, run unit tests and test building of
 214 rpm and Debian packages in a Docker:
 215
 216     docker build  --no-cache -f docker_test/Dockerfile-Test -t sdltest:latest .
 217
 218 If needed, ready rpm and Debian packages can be copied from Docker to host. In
 219 below example packages are copied to host's /tmp/sdltest-packages directory:
 220
 221     docker run -v /tmp/sdltest-packages:/export sdltest:latest /export
 222
 223 ## Using SDL in application pod
 224
 225 SDL is not yet available in O-RAN-SC PackageCloud.io repository.
 226
 227 Plan is to add it, but in the meantime SDL API needs to be complied and installed
 228 in SDL client Dockerfiles (refer instructions above). You may need to execute
 229 `RUN ldconfig` command to Dockerfile after SDL API installation.
 230
 231 RIC DBaaS service must be running before starting application pod which is using SDL
 232 API. DBaaS defines environment variables which are used to contact DBaaS service
 233 (offering backend for SDL). Those environment variables are exposed inside application
 234 container only if DBaaS service is running when application container is started.
 235
 236 You may test SDL connectivity to its backend with `sdltool test-connectivity`
 237 command inside your application container.