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