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     boost
  41     hiredis
  42     doxygen (optional)
  43
  44 Commands to install dependent packages in Fedora:
  45
  46     sudo dnf install boost-devel
  47     sudo dnf install hiredis-devel
  48     sudo dnf install doxygen
  49
  50 Commands to install dependent packages in Debian/Ubuntu:
  51
  52     sudo apt install libboost-all-dev
  53     sudo apt install libhiredis-dev
  54     sudo apt install doxygen
  55
  56 ### Compilation in the source directory
  57
  58     cd shareddatalayer
  59     ./autogen.sh
  60     ./configure
  61     make all test
  62
  63 ### Compilation outside the source directory
  64
  65     cd shareddatalayer
  66     ./autogen.sh
  67     cd ..
  68     mkdir workdir
  69     cd workdir
  70     ../shareddatalayer/configure
  71     make all test
  72
  73 ## Installation
  74
  75 By default the shared library is installed to `/usr/local/lib` and
  76 headers into to `/usr/local/include`. If this is not desired, then
  77 provide different path when running `configure`, for example:
  78
  79     ./configure --prefix=$HOME/usr/local
  80
  81 In above example SDL pkg-config .pc file is installed to `$HOME/usr/local/lib/pkgconfig`
  82 directory. This directory should be included to `PKG_CONFIG_PATH` while building
  83 the application which is using the SDL API library.
  84
  85 Note that `configure` command allows plethora of additional options.
  86 For more info:
  87
  88     ./configure --help
  89
  90 After configuration has been done, run:
  91
  92     make install
  93
  94 In some cases dynamic linker cache needs to be manually refreshed after SDL API
  95 has been re-installed:
  96
  97     ldconfig
  98
  99 ### Redis modules
 100
 101 When Redis is used, SDL requires that the following Redis extension commands
 102 have been installed to runtime environment:
 103 - MSETPUB
 104 - SETIE
 105 - SETIEPUB
 106 - SETNXPUB
 107 - DELPUB
 108 - DELIE
 109 - DELIEPUB
 110
 111 Redis v4.0 or greater is required. Older versions do not support extension
 112 modules.
 113
 114 Implementation for these commands is produced by RIC DBaaS:
 115 https://gerrit.o-ran-sc.org/r/admin/repos/ric-plt/dbaas
 116
 117 In official RIC deployments these commands are installed by `dbaas` service to
 118 Redis container(s).
 119
 120 In development environment you may want install commands manually to pod/container
 121 which is running Redis.
 122
 123 Installation to default system directory:
 124
 125     cd redismodule
 126     ./autogen.sh
 127     ./configure
 128     make install
 129
 130 Following line should be added to `redis.conf` file:
 131
 132     loadmodule <path>/libredismodule.so
 133
 134 `<path>` should be replaced to match library installation directory path.
 135 `redis-server` must be restarted after configuration file update.
 136
 137 Notice that `redis-server` takes path to configuration file as an argument.
 138 If not given it will start with default parameter values and above made
 139 `loadmodule` option is not effective. Refer to `redis-server --help`.
 140
 141 SDL API will check in connection setup phase that all required commands are
 142 available, if not then execution is aborted and error log is written to identify
 143 that which commands are missing.
 144
 145 ## Running unit tests
 146
 147 Unit tests are compiled and executed by simply running:
 148
 149     make test
 150
 151 By default all unit tests are executed. If `valgrind` is installed,
 152 then by default unit test execution is analyzed with `valgrind`.
 153 Running specific test cases can be achieved by using `GTEST_FILTER`
 154 environment variable. For example:
 155
 156     make test GTEST_FILTER=ConnectionTest*
 157
 158 If `valgrind` is not desired (even if installed), then it can be
 159 disabled with `USE_VALGRIND` environment variable:
 160
 161     make test USE_VALGRIND=false
 162
 163 Additional `valgrind` arguments can be specified with `VALGRIND_EXTRA_ARGS`
 164 environment variable. For example:
 165
 166     make test VALGRIND_EXTRA_ARGS='--track-fds=yes --log-file=mylog.txt'
 167
 168 It is also possible to use the `testrunner` binary directly (after it
 169 has been compiled). The `testrunner` binary supports all the command
 170 line options gtest supports, for example:
 171
 172     make testrunner
 173     ./testrunner --help
 174
 175 ## Using SDL in application pod
 176
 177 SDL is not yet available in O-RAN-SC PackageCloud.io repository.
 178
 179 Plan is to add it, but in the meantime SDL API needs to be complied and installed
 180 in SDL client Dockerfiles (refer instructions above). You may need to execute
 181 `RUN ldconfig` command to Dockerfile after SDL API installation.
 182
 183 RIC DBaaS service must be running before starting application pod which is using SDL
 184 API. DBaaS defines environment variables which are used to contact DBaaS service
 185 (offering backend for SDL). Those environment variables are exposed inside application
 186 container only if DBaaS service is running when application container is started.
 187
 188 You may test SDL connectivity to its backend with `sdltool test-connectivity`
 189 command inside your application container.