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
  65
  66 Note that `configure` command allows plethora of additional options.
  67 For more info:
  68
  69     ./configure --help
  70
  71 After configuration has been done, run:
  72
  73     make install
  74
  75 ### Redis modules
  76
  77 When Redis is used, SDL requires that the following Redis extension commands
  78 have been installed to runtime environment:
  79 - MSETPUB
  80 - SETIE
  81 - SETIEPUB
  82 - SETNXPUB
  83 - DELPUB
  84 - DELIE
  85 - DELIEPUB
  86
  87 Redis v4.0 or greater is required. Older versions do not support extension
  88 modules.
  89
  90 Implementation for these commands is produced by RIC DBaaS:
  91 https://gerrit.o-ran-sc.org/r/admin/repos/ric-plt/dbaas
  92
  93 In official RIC deployments these commands are installed by `dbaas` service to
  94 Redis container(s).
  95
  96 In development environment you may want install commands manually to pod/container
  97 which is running Redis.
  98
  99 Installation to default system directory:
 100
 101     cd redismodule
 102     ./autogen.sh
 103     ./configure
 104     make install
 105
 106 Following line should be added to `redis.conf` file:
 107
 108     loadmodule <path>/libredismodule.so
 109
 110 `<path>` should be replaced to match library installation directory path.
 111 `redis-server` must be restarted after configuration file update.
 112
 113 Notice that `redis-server` takes path to configuration file as an argument.
 114 If not given it will start with default parameter values and above made
 115 `loadmodule` option is not effective. Refer to `redis-server --help`.
 116
 117 SDL API will check in connection setup phase that all required commands are
 118 available, if not then execution is aborted and error log is written to identify
 119 that which commands are missing.
 120
 121 ## Running unit tests
 122
 123 Unit tests are compiled and executed by simply running:
 124
 125     make test
 126
 127 By default all unit tests are executed. If `valgrind` is installed,
 128 then by default unit test execution is analyzed with `valgrind`.
 129 Running specific test cases can be achieved by using `GTEST_FILTER`
 130 environment variable. For example:
 131
 132     make test GTEST_FILTER=ConnectionTest*
 133
 134 If `valgrind` is not desired (even if installed), then it can be
 135 disabled with `USE_VALGRIND` environment variable:
 136
 137     make test USE_VALGRIND=false
 138
 139 Additional `valgrind` arguments can be specified with `VALGRIND_EXTRA_ARGS`
 140 environment variable. For example:
 141
 142     make test VALGRIND_EXTRA_ARGS='--track-fds=yes --log-file=mylog.txt'
 143
 144 It is also possible to use the `testrunner` binary directly (after it
 145 has been compiled). The `testrunner` binary supports all the command
 146 line options gtest supports, for example:
 147
 148     make testrunner
 149     ./testrunner --help
 150
 151 ## Using SDL in application pod
 152
 153 SDL is not yet available in O-RAN-SC PackageCloud.io repository.
 154
 155 Plan is to add it, but in the meantime SDL API needs to be complied and installed
 156 in SDL client Dockerfiles (refer instructions above). You may need to execute
 157 `RUN ldconfig` command to Dockerfile after SDL API installation.
 158
 159 RIC DBaaS service must be running before starting application pod which is using SDL
 160 API. DBaaS defines environment variables which are used to contact DBaaS service
 161 (offering backend for SDL). Those environment variables are exposed inside application
 162 container only if DBaaS service is running when application container is started.
 163
 164 You may test SDL connectivity to its backend with `sdltool test-connectivity`
 165 command inside your application container.